Layout & content

Surface / surfaceStyles

A themed structural container that groups related content without imposing semantics.

SurfacesurfaceStylesSurfacePropsSurfaceVariantSurfacePaddingSurfaceInteraction

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Structured content surface

Semantic variants and spacing stay aligned with the shared token system.

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

import { Surface } from '@ai-created/ui';

export function Example() {
  return (
    <Surface>
      <h2>Project status</h2>
      <p>Related content belongs inside the surface.</p>
    </Surface>
  );
}

Import

tsx

import { Surface, surfaceStyles } from '@ai-created/ui';

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Container

Required

Bordered visual grouping root.

div

Content slot

Required

Free-form content that supplies the surface meaning.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Layout/Surface

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish as a container component with nested content enabled.

Auto layout

Direction: vertical
Gap: Inherited from content
Padding: 0, 16px, 24px, 32px, 40px, or responsive 32px/48px
Alignment: Stretch children horizontally
Wrap: Content controlled

The component supplies padding only; child spacing belongs to the content composition.

Resizing

Width: fill
Height: hug
Minimum width: 0px
Maximum width: Parent controlled
Minimum height: 0px
Maximum height: Content controlled
Overflow: visible

Use fixed height only for an explicitly specified media or data region.

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
Variant	variant	default	variant	default, muted, accent, inset, success, warning, info, error
Padding	variant	none	padding	none, sm, md, lg, xl, responsive
Interaction	variant	none	interaction	none, group, within
ContentRequired	slot	None	children	No additional constraint

Nested assets and slots

Content

slot / required

Consumer-owned semantic content.

children

Content limits

Nested surfaces

Maximum one bordered child layer in ordinary product UI

Overflow: Flatten excess wrappers or remove an inner border.

Repeated framed layers obscure hierarchy.

Localization and RTL

Translatable: Nested content only

Container geometry is direction-neutral; nested content owns direction.
Test with long nested copy and mixed-direction content.

Responsive behavior

Fill its parent while height follows content.

md: responsive padding changes from 32px to 48px

Responsive padding is the only built-in breakpoint behavior.
Parent grids own column changes.

Authoring limits

Interaction variants are visual demonstrations and do not make the Figma layer operable.
Surface has no semantics or interaction by itself; use a semantic wrapper when needed.

Accountable owner

Design systems layout primitive owner

Canonical source: src/components/Surface.tsx

New variants must map to an approved semantic surface token pair.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Radius

6px

Border

1px

Padding

0 / 16 / 24 / 32 / 40px

none / sm / md / lg / xl.

Responsive padding

32px, then 48px at md

Rules

Pick a surface variant for structural or semantic meaning.
Interaction styling only supplies visual feedback; the consumer owns interactive semantics.

Responsive behavior

Responsive padding increases at the md breakpoint.
Width is controlled by the parent layout.

Token dependencies

--color-surface / --color-surface2 / --color-bg

Structural backgrounds.

--color-border / --color-border-strong

Default border and interaction emphasis.

--color-accent-border

Accent border.

--color-*-surface / --color-*-border

Semantic variants.

--radius-md

Corner radius.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

default

Trigger: No interaction.
Visual response: Stable themed fill and 1px border.
Behavior: Pure layout container.

interactive group

Trigger: A parent group is hovered or focus-visible.
Visual response: Border strengthens; accent surfaces use the accent border.
Behavior: Feedback follows the parent control.

interactive within

Trigger: The surface is hovered or contains focus.
Visual response: Border strengthens over 200ms.
Behavior: Does not become keyboard interactive by itself.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Default element is a non-semantic <div>. surfaceStyles can style another semantic root.
Accessible name: The surface has no name by default.

Add a heading, region label, list semantics, or interactive wrapper when content needs structure.
Never imply clickability through interaction styling without a keyboard-operable element.

Keyboard behavior

No component-specific keyboard behavior. Native document behavior remains unchanged.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { Surface, surfaceStyles } from '@ai-created/ui';

Server Component compatible

Surface forwards a div ref and native HTML attributes.
Use surfaceStyles to apply the same visual contract to a semantic article, section, or link.

tsx

<Surface variant="muted" padding="md">Content</Surface>

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
variant	SurfaceVariant	default	default, muted, accent, inset, success, warning, info, or error.
padding	SurfacePadding	none	none, sm, md, lg, xl, or responsive.
interaction	SurfaceInteraction	none	none, group, or within interaction styling.
className	string	undefined	Additional classes.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Use consistent padding for peer surfaces.
Choose inset when the content should visually recede.

Do not

Do not nest multiple bordered surfaces without a clear hierarchy.
Do not add group interaction to a non-interactive card.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Maps every variant, padding, and interaction value.
Consumer className overrides default utilities.

Interaction

Group and focus-within borders respond to their documented triggers.

Accessibility

Semantic wrappers retain their roles and names.

Visual

Cover all variants plus interaction borders in both themes.

Related specifications

notice empty-state modal