Primitive contract

Surface

Creates a restrained visual plane from package surface, border, radius, and elevation tokens while leaving content semantics to the chosen element.

Semantic visual plane · @sanchika/primitives

Purpose and semantics

Creates a restrained visual plane from package surface, border, radius, and elevation tokens while leaving content semantics to the chosen element.

Recommended semantic: Choose article, section, aside, div, fieldset, or another semantic element based on content; Surface adds no role.

Anatomy

root

The semantic element that owns the visual plane.

content

Consumer-owned semantic content.

Finite variants and important states

Variant · variant: default, raised, inset, muted, inverse
Variant · padding: none, sm, md, lg
Required states: default, forced-colors
Class hooks: .sk-surface · .sk-surface-default · .sk-surface-raised · .sk-surface-inset · .sk-surface-muted · .sk-surface-inverse · .sk-surface-pad-none · .sk-surface-pad-sm · .sk-surface-pad-md · .sk-surface-pad-lg

Composed synthetic exemplar

Rendered state matrix

Surface: 2 required states

Each specimen starts from the package-owned example and contract state inventory. Simulated pointer and focus frames are labelled; consumers still verify real interaction in context.

defaultSettled and available for its documented job.

forced colorsSystem colors retain boundaries and focus semantics.

Accessibility and consumer responsibility

Keyboard and screen reader

Static Surface is not focusable; interactive descendants own their keyboard behavior.
Do not add a role solely because the plane is visually distinct.

Consumer owns

Choose the semantic element
Name visible state in content
Avoid decorative nesting

Mobile

Remains within the available inline size
Padding stays finite and token-driven

Reduced motion and forced colors

No override is needed because the primitive adds no motion.

Uses a CanvasText boundary
Inverse variants return to system Canvas and CanvasText

Compact API reference

Package: @sanchika/primitives
CSS: @sanchika/primitives/styles.css
Contract: primitiveSpecs.find((contract) => contract.name === "Surface")
Primary class: .sk-surface