Skip to content
Cloaked Design SystemFoundations

Surfaces

Build a clear sense of place. Explore page, content, input, and inverse surfaces in one readable composition.

Implementation preview
01

Give each layer a clear purpose

See page, surface, subtle, and inverse roles together. Switch themes to inspect how their foregrounds and backgrounds work as pairs.

Live exampleReact · shared implementation
Try the controls. Your changes stay in this example.Open example
COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

2 stories
SELECTED EXAMPLE

Theme Surfaces

Open controls
Theme Surfaces selectedOpen canvas
Example sourcepackages/design-system/src/foundations/Foundations.stories.tsxExport ThemeSurfaces

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Full story catalog JSON ↗
02

Choose with the experience in mind

01

Give the container a purpose

Use the page as the foundation and a surface to group related content. Add another container only when it communicates a separate responsibility.

02

Choose the foreground as well

Text suited to the page can disappear on an inverse or status surface. Use the appropriate semantic foreground and verify labels, helper text, and controls together.

03

Let the theme resolve the value

Keep the role name when changing themes. The reference preserves each light and dark definition so the same layout can adapt without replacing tokens with raw colors.

03

Keep the exact definition close

These values come directly from the design-owned source. Aliases, expressions, theme selectors, and source files are retained.

Full surfaces reference 28 definitions
TokenSource valueSelectorSource file
var(--cds-color-grey-01)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-color-grey-01)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-color-white)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-color-black)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-color-black)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-status-success-subtle)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-status-warning-subtle)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-status-danger-subtle)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-status-info-subtle)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-color-grey-01)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-color-black)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-color-grey-06)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-color-grey-01)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-color-white-15)[data-theme='light']packages/design-system/src/tokens/themes.css
var(--cds-color-grey-07)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-color-black)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-color-grey-06)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-color-black)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-color-white)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-status-success-solid)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-status-warning-solid)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-status-danger-solid)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-status-info-solid)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-color-grey-05)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-color-black)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-color-grey-06)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-color-white-05)[data-theme='dark']packages/design-system/src/tokens/themes.css
var(--cds-color-white-15)[data-theme='dark']packages/design-system/src/tokens/themes.css

Design-owned preview Version 0.2.0-preview.1 28 definitions

04

Build from the same decisions

Give an agent the guidance, source values, and working example together.

Agent handoff
Use the Cloaked surfaces foundations.
Read https://design.cloaked.team/data/foundations/surfaces.json first.
Use the exact token names, values, and theme selectors in this contract.
Check the shared foundation-surfaces example and preserve its visual intent.
Verify keyboard access, both themes, responsive layout, and reduced-motion behavior where applicable.
Treat this design-owned version as an implementation preview, pending sign-off.
Surfaces contract JSON Complete token source JSON Build with an agent Guide
Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1