Overview
The Surface component is a versatile container element that provides a foundation for cards, panels, and other UI containers. It offers flexible styling options for background, padding, and border radius to accommodate various design needs.
Key Features
- 3 visual variants (default, soft, elevated)
- 4 padding options (none, sm, md, lg)
- 5 border radius options (none, md, xl, 2xl, 3xl)
- Responsive padding that adapts to screen size
- Slot-based content for maximum flexibility
Variants
Default
White background with subtle border. Standard surface for cards and containers.
Default Surface
This is a default surface with white background and a subtle border.
Soft
Subtle gray background without border. Gentle alternative surface for nested containers.
Soft Surface
This is a soft surface with neutral-50 background and no border.
Elevated
White background with border and shadow. Creates depth and emphasis.
Elevated Surface
This is an elevated surface with shadow for added depth and prominence.
Padding Options
Padding is responsive - medium and large sizes increase on larger screens.
None (p-0)
No padding - useful when you want full control over internal spacing.
Small (p-3 / 12px)
Small padding for compact containers and tight spaces.
Medium (p-4 md:p-5 / 16-20px)
Medium padding (default) - balanced spacing for most use cases. Increases to 20px on tablet and above.
Large (p-6 md:p-8 / 24-32px)
Large padding for spacious containers and feature sections. Increases to 32px on tablet and above.
Border Radius Options
None (0px)
Sharp corners
Medium (6px)
Subtle rounding
XL (12px)
Moderate rounding
2XL (16px) - Default
Comfortable rounding
3XL (24px)
Prominent rounding for feature cards
Combination Examples
Standard Card
Alert Card
This is a standard card with default variant, large padding, and 2xl rounding.
Feature Panel
Protected & Secure
Your data is encrypted and protected with industry-leading security measures.
Nested Surfaces
Outer Container
Nested soft surface - great for grouping related content
Another nested section with consistent styling
Compact List Items
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | string | 'default' | Visual style: 'default', 'soft', 'elevated' |
| padding | string | 'md' | Internal padding: 'none', 'sm', 'md', 'lg' |
| rounded | string | '2xl' | Border radius: 'none', 'md', 'xl', '2xl', '3xl' |
| class | string | '' | Additional CSS classes |
Usage Examples
Basic Surface
<x-building-blocks.surface>
Your content here
</x-building-blocks.surface>With Custom Props
<x-building-blocks.surface
variant="elevated"
padding="lg"
rounded="3xl"
>
Feature content
</x-building-blocks.surface>Nested Surfaces
<x-building-blocks.surface variant="default" padding="lg">
<h3>Main Container</h3>
<x-building-blocks.surface variant="soft" padding="md">
Nested content
</x-building-blocks.surface>
</x-building-blocks.surface>With No Padding
<x-building-blocks.surface padding="none">
<img src="image.jpg" alt="Full bleed image" />
</x-building-blocks.surface>Usage Guidelines
When to Use Each Variant
- Default: Standard cards, panels, and containers
- Soft: Nested containers, secondary groupings, subtle backgrounds
- Elevated: Feature cards, modals, important content that needs emphasis
Padding Guidelines
- None: Full-bleed images, custom internal layouts
- Small: Compact list items, tight spaces
- Medium: Standard cards and containers (default)
- Large: Feature sections, spacious layouts
Border Radius Selection
- None: Technical interfaces, data tables
- Medium: Subtle rounding for compact elements
- XL-2XL: Standard cards and containers (2xl is default)
- 3XL: Feature cards, hero sections, prominent elements
Best Practices
Do
- • Use default variant for most containers
- • Use soft variant for nested surfaces
- • Use elevated variant sparingly for emphasis
- • Match padding to content density
- • Use consistent rounding within a section
- • Leverage responsive padding (md, lg)
Don't
- • Overuse elevated variant (creates visual noise)
- • Mix too many border radius sizes
- • Use large padding for compact lists
- • Nest elevated surfaces
- • Forget to consider mobile spacing
- • Use surface for every container
Accessibility
Considerations
-
Semantic HTML: Surface is a generic container - add appropriate semantic elements inside (article, section, etc.)
-
Color Contrast: All variants maintain sufficient contrast for text content
-
Focus Management: Ensure interactive elements inside surfaces have proper focus indicators
-
Responsive Design: Padding automatically adjusts for better mobile experience