Navigation & layoutBrick 0.1.2

Surface

Surface paints a semantic region with a controlled background level, optional border, elevation, radius, and inset. It renders one native element and adds no layout, clipping, interaction, role, or runtime color context.

Live example

Built from the published package

Interactive

Base

Subtle

Raised

Choose with confidence

Know when Surface is the right part

Use it when

Use Surface for generic painted regions such as application sections, workspaces, specimen panels, and nested background layers. Combine it with Container for page measure and Stack or Grid for child layout.

Choose another path when

Use Card for a self-contained content object, modal components for interactive overlays, and application CSS for product-specific decoration. Surface is not a Box, layout primitive, theme provider, or substitute for semantic HTML.

Installation and imports

tsx

import { Surface } from "@flowstack-ui/brick";
// or
import { Surface } from "@flowstack-ui/brick/surface";

import "@flowstack-ui/brick/styles.css";

The complete stylesheet above is the recommended default. For a measured route-aware build, replace it with the shared foundation and this component's stylesheet:

tsx

import "@flowstack-ui/brick/styles/core.css"; // once at the application root
import "@flowstack-ui/brick/styles/surface.css";

Add the modular stylesheet for every other Brick component the route renders. Do not combine modular styles with styles.css or tokens.css.

Public exports are Surface, SurfaceProps, SurfaceElement, SurfaceLevel, SurfaceElevation, SurfaceRadius, and SurfaceInset.

Quick start

tsx

<Surface as="section" bordered inset="md" level="subtle">
  <VStack gap="3">
    <Text as="h2" variant="title-md">Release readiness</Text>
    <Text>All required evidence is available.</Text>
  </VStack>
</Surface>

Visual recipes and states

level selects a semantic background layer. Border, elevation, radius, and inset remain independent so consumers can change only the visual dimension they intend to demonstrate. Surface has no hover, focus, selected, disabled, loading, validation, typography, or motion state.

Elevations are deliberately restrained: low separates nearby content, medium separates a stronger floating region, and high is reserved for the strongest non-modal separation. In forced colors, elevated or bordered surfaces use a system border instead of relying on shadow alone.

Examples

Full-width paint with measured content

tsx

<Surface as="section" level="subtle">
  <Container>
    <VStack gap="4">Measured section content</VStack>
  </Container>
</Surface>

Nested semantic levels

tsx

<Surface inset="lg" level="canvas">
  <Surface bordered inset="md" level="raised" elevation="low">
    Focused workspace
  </Surface>
</Surface>

Public contract

API

Start with the public parts and root options below. Components with multiple parts separate each area into its own named subsection.

Prop	Values	Default
`as`	`div`, `section`, `article`, `aside`, `nav`, `main`, `header`, `footer`, `form`, `li`	`div`
`level`	`canvas`, `base`, `subtle`, `raised`	`base`
`bordered`	`boolean`	`false`
`elevation`	`none`, `low`, `medium`, `high`	`none`
`radius`	`none`, `subtle`, `surface`	`surface`
`inset`	`none`, `sm`, `md`, `lg`	`none`
`slot`	`string`	`surface`
`children`	`ReactNode`	optional

Native global/ARIA/data attributes, events, className, style, and an HTMLElement ref pass through.

Shared responsibility

Accessibility

Surface adds no role, accessible name, landmark, focus target, or keyboard behavior. Choose as for the actual document structure and name repeated landmarks when required. Background and foreground variables change together, and forced-colors styling preserves visible boundaries.

Responsive behavior

Surface follows the size of its parent and uses logical padding. It has no responsive props, viewport-height policy, safe-area behavior, or breakpoint logic. Application composition decides how Surface participates in responsive layout.

Stable visual contract

Styling and tokens

Customization

Use recipes first, then override selected variables on a deliberate instance:

tsx

<Surface
  bordered
  inset="md"
  style={{
    "--brick-surface-background": "color-mix(in srgb, Canvas, rebeccapurple 8%)",
    "--brick-surface-border-color": "rebeccapurple",
  }}
>
  Customized region
</Surface>

This escape hatch does not make arbitrary values part of the recipe API.

Tokens and CSS hooks

Stable hooks are .brick-surface, [data-slot="surface"], data-slot, data-level, data-bordered, data-elevation, data-radius, and data-inset.

Public variables:

--brick-surface-background
--brick-surface-foreground
--brick-surface-border-color
--brick-surface-border-width
--brick-surface-elevation-none
--brick-surface-elevation-low
--brick-surface-elevation-medium
--brick-surface-elevation-high
--brick-surface-shadow
--brick-surface-radius
--brick-surface-padding

Advanced reference

Open these details only when you need to inspect DOM ownership, native forwarding, or lower-level composition.

Maintainer resources

Tests, playground evidence, source notes, and release history remain available without crowding the plug-and-play guide.

Source docs Changelog Playground