Surface

Status: Experimental

Surface gives a meaningful interface region a shared background, boundary, and spacing rule. It stays flat and square by design: there is no elevation, shadow, or rounded-card treatment.

Preview

01 / ACCOUNT

Northstar Goods

Active customer · Updated today

Basic usage

---
import { Surface } from '@freightpx/frasto';
---

<Surface as="section" variant="outlined" aria-labelledby="account-heading">
  <h2 id="account-heading">Account</h2>
  <p>Customer and billing details.</p>
</Surface>

Use Surface when a background or boundary communicates a real region. Plain spacing, a heading, or a Separator is often enough when the relationship is already clear.

Variants

Plain surface

Subtle surface

Outlined surface

• plain uses the primary surface color without a border.
• subtle uses the quiet surface token without introducing semantic color.
• outlined adds the standard one-pixel structural border.

All variants remain square and shadowless.

Padding

Padding follows Frasto’s spacing scale. Use none when the child layout owns its spacing, such as an application shell or a table region.

<Surface padding="none">...</Surface>
<Surface padding="sm">...</Surface>
<Surface padding="md">...</Surface>
<Surface padding="lg">...</Surface>

Semantic element

Choose an element that reflects the content relationship rather than its appearance.

<Surface as="article">...</Surface>
<Surface as="aside" aria-label="Account context">...</Surface>
<Surface as="section" aria-labelledby="billing-heading">...</Surface>

The supported elements are div, section, article, and aside. Surface does not add a landmark role or accessible name automatically.

API

Prop	Type	Default	Purpose
as	'div' | 'section' | 'article' | 'aside'	'div'	rendered semantic element
variant	'plain' | 'subtle' | 'outlined'	'plain'	background and boundary treatment
padding	'none' | 'sm' | 'md' | 'lg'	'md'	internal spacing
class	string	—	adds a consumer class

Native global HTML attributes are forwarded.

Accessibility

• Give a semantic section or aside an accessible heading or label when it represents a landmark.
• Do not choose article unless the content can stand on its own.
• Visual boundaries do not replace headings or document structure.
• Surface variants are structural, not status indicators.

Responsive behavior

Surface fills the available inline space as a block and does not impose a width, height, or layout mode on its children. Consumer layouts remain responsible for responsive padding overrides, overflow, and child arrangement.

Restraint

Avoid nesting surfaces only to create visual depth. Prefer typography, whitespace, and separators for subdivisions inside an existing surface. Use a new surface when the boundary remains meaningful after the surrounding page decoration is removed.