# SurfaceDepth (surface-depth)

> Fine borders, inset edge lighting, and layered shadows. Compare the original surface and inspect each layer.

- Entry: doc
- Category: Foundations
- Preview capabilities: controls
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/surface-depth
- JSON: https://jbm-ui.bns.studio/catalog/surface-depth.json
- Registry item: https://jbm-ui.bns.studio/r/tokens.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/tokens
```

Documentation entry, not a registry item: the code it documents ships in @jbm/tokens.

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/tokens.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/lib/tokens.ts` | `src/jbm/lib/tokens.ts` | `@/jbm/lib/tokens` |

## API

### `shadow` (constant)

Complete raised-surface box-shadows: `card` for light surfaces and `cardDark` for ink surfaces. Apply the whole recipe rather than copying layers into components.

### `surfaceBorder` (constant)

The 1px border that defines the silhouette: `card` (ink at 12%) and `cardDark` (ink at 65%). Pair with the shadow of the same name.

### `shadowLayers` (constant)

Each recipe split into `inset` (upper edge highlight and lower inner line), `contact` (1px crisp contact), and `ambient` (offsets 3, 6, 12, 24px with negative spread and falling opacity). The gallery lab toggles these independently.

## Stage

n/a: Documentation entry for token recipes; nothing installs as a component. The gallery lab renders two sample surfaces with layer toggles.

## Examples

### Light raised surface

```tsx
import { shadow, surfaceBorder } from "@/jbm/lib/tokens"

// Light surface (use cardDark for dark surfaces)
<div style={{
  boxShadow: shadow.card,
  border: surfaceBorder.card,
}} />
```

### Dark surface

```tsx
import { color, radius, shadow, surfaceBorder } from "@/jbm/lib/tokens"

<div style={{
  background: color.codeBg,
  borderRadius: radius.card,
  boxShadow: shadow.cardDark,
  border: surfaceBorder.cardDark,
}} />
```

## QA

- Toggle Before and Layered: Before shows the original single broad shadow and 2px border and disables the layer controls.
- Toggle border, inset highlight, contact shadow, and soft outer shadows one at a time on both the light and dark samples; each change should be visible and none should leave a clipped shadow.
- Inspect at actual display scale: edges readable without looking embossed, and the highlight reads as edge light rather than a separate stripe.
- Press Copy token usage with and without clipboard access; the status line reports success or points to the Usage snippet.
- Exercise the buttons and checkboxes by keyboard and confirm visible focus.

## Docs

- [Surface depth guide](https://jbm-ui.bns.studio/docs/surface-depth.md)

## Related

Installed by: 67 items (see https://jbm-ui.bns.studio/catalog.json).

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
