Box

A foundational layout primitive with theming support. Box provides a simple, semantic container with color, elevation, and padding options — the perfect building block for layouts and compositions.

Features

• 🎨 4 Variants: solid, flat, glass, frost
• 🌈 6 Color Themes: primary, secondary, info, success, warning, error
• 🌟 Rainbow Border: Animated rainbow border with glow effect
• 📏 5 Padding Sizes: none, sm, md, lg, xl
• 🎭 6 Elevation Levels: Customizable shadow depths (0–5)
• 🧱 Foundation Component: Designed to be the base for layouts and compositions
• 🎨 Customizable: CSS custom properties for complete control

Source Code

View Source Code

import { defineComponent, html } from '@vielzeug/craftit';

import type { ElevationLevel, PaddingSize, RoundedSize, ThemeColor } from '../../types';

import { frostVariantMixin, rainbowEffectMixin, surfaceMixins } from '../../styles';
import componentStyles from './box.css?inline';

/** Box component properties */
export type BitBoxProps = {
  /** Theme color */
  color?: ThemeColor;
  /** Shadow elevation level (0–5) */
  elevation?: `${ElevationLevel}`;
  /** Full width mode (100% of container) */
  fullwidth?: boolean;
  /** Internal padding size */
  padding?: PaddingSize;
  /** Enable animated rainbow border effect */
  rainbow?: boolean;
  /** Border radius size */
  rounded?: RoundedSize;
  /** Visual style variant */
  variant?: 'solid' | 'flat' | 'glass' | 'frost';
};

/**
 * bit-box — A foundational layout primitive with theming support.
 *
 * @element bit-box
 *
 * @attr {string} variant - Style variant: 'solid' | 'flat' | 'glass' | 'frost'
 * @attr {string} color - Color theme: 'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error'
 * @attr {string} padding - Padding size: 'none' | 'sm' | 'md' | 'lg' | 'xl'
 * @attr {string} elevation - Shadow elevation: '0' | '1' | '2' | '3' | '4' | '5'
 * @attr {string} rounded - Border radius: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'
 * @attr {boolean} rainbow - Enable animated rainbow border effect
 * @attr {boolean} fullwidth - Expand to full width
 *
 * @slot - Default slot for content
 *
 * @part box - The inner box element
 *
 * @cssprop --box-bg - Background color
 * @cssprop --box-color - Text color
 * @cssprop --box-border - Border width
 * @cssprop --box-border-color - Border color
 * @cssprop --box-radius - Border radius
 * @cssprop --box-padding - Inner padding
 * @cssprop --box-shadow - Box shadow
 *
 * @example
 * ```html
 * <bit-box padding="lg" elevation="2">Simple content</bit-box>
 * <bit-box variant="glass" color="primary">Glass effect</bit-box>
 * <bit-box variant="frost" rainbow>Frosted glass</bit-box>
 * ```
 */
export const BOX_TAG = defineComponent({
  setup() {
    return html`<div class="box" part="box"><slot></slot></div>`;
  },
  styles: [...surfaceMixins, rainbowEffectMixin('.box'), frostVariantMixin('.box'), componentStyles],
  tag: 'bit-box',
});

Basic Usage

Default box with canvas background and gentle border.

PreviewCode

RTL

Variants

Four variants cover the full range from solid to translucent.

• Default (no variant) — Canvas background with border and subtle shadow. Picks up color as a tinted backdrop.
• flat — Same as default but with no shadow; low visual weight.
• glass — Glassmorphism with backdrop blur, saturated colors, and brightness boost.
• frost — Frosted glass with stronger blur and color-tinted transparency.

PreviewCode

RTL

Glass & Frost

Translucent effects with backdrop blur — best used over rich backgrounds.

Best Used With

Glass and frost look best over colorful backgrounds or images to make the blur and transparency visible.

PreviewCode

RTL

Colors

Six semantic colors for different contexts. Hover state is included for solid and flat when a color is set.

PreviewCode

RTL

Elevation

Control shadow depth with elevation levels from 0 to 5.

PreviewCode

RTL

Padding

Choose from five padding sizes.

PreviewCode

RTL

Rainbow Border

Animated rainbow border effect — works on any variant.

PreviewCode

RTL

API Reference

Attributes

Attribute	Type	Default	Description
variant	'solid' | 'flat' | 'glass' | 'frost'	-	Style variant
color	'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error'	-	Color theme
padding	'none' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Internal padding
elevation	'0' | '1' | '2' | '3' | '4' | '5'	-	Shadow depth (0–5)
rounded	'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'	'md'	Border radius
rainbow	boolean	false	Animated rainbow border effect
fullwidth	boolean	false	Expand to full width

Slots

Slot	Description
(default)	Main content of the box

Parts

Part	Description
box	The inner <div> — target with ::part

CSS Custom Properties

CSS custom properties work regardless of whether a color attribute is set.

Property	Default	Description
--box-bg	var(--color-canvas)	Background
--box-color	var(--color-contrast-900)	Text color
--box-border	var(--border)	Border width
--box-border-color	var(--color-contrast-300)	Border color
--box-radius	var(--rounded-lg)	Border radius
--box-padding	var(--size-4)	Inner padding
--box-shadow	var(--shadow-sm)	Box shadow

Accessibility

The box component follows WAI-ARIA best practices.

bit-box

✅ Semantic Structure

• Supports all standard ARIA attributes (aria-label, aria-describedby, role, etc.).
• Elevation changes are purely visual and do not affect accessibility.

✅ Screen Readers

• Glass and frost variants maintain readable contrast ratios.

Best Practices

Do:

• Wrap bit-box in a semantic HTML element (<section>, <article>, etc.) when the content warrants it.
• Combine color and elevation to create visual hierarchy without custom CSS.
• Use glass and frost variants only over rich backgrounds where the blur effect is visible.
• Use --box-* custom properties on a parent for contextual theming instead of inline styles.

Don't:

• Rely only on color to convey meaning — box is a container, not a status indicator.
• Nest too many bit-box elements — keep structural depth reasonable for maintainability.