# DeskTop (desk-top)

> A cream desk seen from above, with light, a tilt-revealed front edge, and an optional pulled-out drawer.

- Entry: component
- Category: UI Bits
- Preview capabilities: controls
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/desk-top
- JSON: https://jbm-ui.bns.studio/catalog/desk-top.json
- Registry item: https://jbm-ui.bns.studio/r/desk-top.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/desk-top
```

Also installs @jbm/tokens, @jbm/scene-geometry (registry dependencies install automatically).

## 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/desk-top.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/desk-top.tsx` | `src/jbm/ui/desk-top.tsx` | `@/jbm/ui/desk-top` |

## API

### `DeskTop` (component)

SVG <g> of a top-down desk: an empty cream surface with an ink edge that sheets, axes, and props lie on, an optional open drawer pulled out at one edge, and a front edge band the camera tilt reveals. It owns no sheets, axes, hands, or drawer contents; compose Ejes, DeskProp, Paper, or Cajon on top. Controlled; no internal timer. Render inside an <svg>.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `box` | `Box` | required | Desk footprint { x, y, w, h } in the parent SVG's user units, including the front edge band and any drawer region. Tilt and the drawer never change it. |
| `light` | `number` | `1` | Light on the whole desk, 0–1 (1 full cream): every fill mixes in OKLab toward the palette's line token, reaching it at 0.72 (the visual language's deepest folder), then toward ink (deskLight). The ink stroke and the ink drawer pull do not change. Clamped. |
| `edge` | `number` | `0` | Camera tilt, 0–1: reveals a front band up to 22 units tall at 1, taken out of the surface's depth: the desk's front edge under the desk top, and a side drawer's own near face under it. 0 is straight down. Clamped. |
| `drawer` | `DeskTopDrawerSide` | none | Edge that holds an open drawer (start left, end right, top, bottom). The drawer box is pulled out past the desk top's edge, which is the one seam line, and is narrower than the desk along it; its outer wall is its front, thicker than the other walls and carrying the pull (an ink bar, the same pull as on Cajon's front, seen from above). Its opening is darker than the desk and runs on under the desk top. Omit for no drawer. |
| `drawerSize` | `number` | none | Drawer region depth across its edge in parent units, the 6-unit seam included: along the width for start and end, along the height for top and bottom. Defaults to 40% of that dimension; kept between 44 and 80% of the plan. |

### `deskTopLayout` (function)

Desk geometry for composites: where the flat surface is, where its centre is (Ejes cross there by default), and the drawer's region, box, opening, front, and pull.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `box` | `Box` | required | Desk footprint { x, y, w, h } in the parent SVG's user units, including the front edge band and any drawer region. Tilt and the drawer never change it. |
| `light` | `number` | `1` | Light on the whole desk, 0–1 (1 full cream): every fill mixes in OKLab toward the palette's line token, reaching it at 0.72 (the visual language's deepest folder), then toward ink (deskLight). The ink stroke and the ink drawer pull do not change. Clamped. |
| `edge` | `number` | `0` | Camera tilt, 0–1: reveals a front band up to 22 units tall at 1, taken out of the surface's depth: the desk's front edge under the desk top, and a side drawer's own near face under it. 0 is straight down. Clamped. |
| `drawer` | `DeskTopDrawerSide` | none | Edge that holds an open drawer (start left, end right, top, bottom). The drawer box is pulled out past the desk top's edge, which is the one seam line, and is narrower than the desk along it; its outer wall is its front, thicker than the other walls and carrying the pull (an ink bar, the same pull as on Cajon's front, seen from above). Its opening is darker than the desk and runs on under the desk top. Omit for no drawer. |
| `drawerSize` | `number` | none | Drawer region depth across its edge in parent units, the 6-unit seam included: along the width for start and end, along the height for top and bottom. Defaults to 40% of that dimension; kept between 44 and 80% of the plan. |

Returns: { box, surface, center, drawer, front, plan, slab, drawn, fill }: surface is the flat top Box; center its centre; drawer is { panel, body, well, front, pull } or null (panel the whole region, body the pulled-out box inside it, well its opening, front its thicker outer wall, pull the ink bar on it); front is the edge band Box (h 0 when flat); plan the surface, seam, and drawer region above the band; slab the desk top as drawn, out to the seam line; drawn is drawing geometry for DeskTop itself; fill holds the surface, handle (kept for compatibility; the pull is ink), front, panel, and well colours after light. All in parent SVG units.

### `deskLight` (function)

A #rrggbb token colour under light k, kept on the palette: mixed in OKLab toward the line token as k falls from 1 to 0.72, then from line toward ink. DeskTop's fills use it.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `hex` | `string` | required | A #rrggbb colour, normally a jbm token such as color.bg or color.card. |
| `k` | `number` | required | Light, 0–1 (clamped): 1 returns the colour, 0.72 the line token, 0 ink. |

Returns: The lit colour as #rrggbb.

### `deskShade` (function)

Scales a #rrggbb colour's OKLab lightness by k (clamped 0–1), keeping its chroma. Kept for compatibility; DeskTop now lights its fills with deskLight, which stays on the palette.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `hex` | `string` | required | A #rrggbb colour, normally a jbm token such as color.bg. |
| `k` | `number` | required | Lightness multiplier, 0–1. |

Returns: The shaded colour as #rrggbb.

### `DESK_EDGE` (constant)

Front edge band height at full tilt (edge 1), in parent units: 22.

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 1680 | 830 |
| Vertical (1080×1920) | 936 | 1340 |

The desk fills its box exactly (parent SVG units = stage pixels in a 1920 × 1080 or 1080 × 1920 composition). The numbers are the safe area the act 2 layout gives it: landscape 1920 − 2 × 120 by 920 − 90, vertical 1080 − 2 × 72 by 1440 − 100. Tilt and the drawer region stay inside the box.

## Examples

### Desk with the drawer kept in frame on the right

```tsx
import { DeskTop } from "@/jbm/ui/desk-top"

<svg viewBox="0 0 1920 1080">
  <DeskTop box={{ x: 120, y: 90, w: 1680, h: 830 }} drawer="end" drawerSize={520} />
</svg>
```

### Axes on the surface, tilting to show the desk edge

```tsx
import { DeskTop, deskTopLayout } from "@/jbm/ui/desk-top"
import { Ejes } from "@/jbm/ui/ejes" // install @jbm/ejes separately

const desk = { box: { x: 120, y: 90, w: 1680, h: 830 }, edge: 1 }
const { surface } = deskTopLayout(desk)
<svg viewBox="0 0 1920 1080">
  <DeskTop {...desk} />
  <Ejes box={surface} h={1} v={1} quiet
    labels={{ top: "hacer", bottom: "entender", left: "aprender", right: "trabajar" }} />
</svg>
```

## QA

- At index size the default (Tilted, drawer end) reads as a desk with a drawer pulled out, not a tablet: a plain cream top with its front edge, and a narrower drawer box with a pull on its outer front.
- Drag Edge from Flat to Tilted: the front band grows from the bottom inside the box, the surface loses the same depth, their shared edge stays one line with square corners where they meet, and a side drawer shows its own near face.
- Step Drawer through none, start, end, top, and bottom: the box never moves; the drawer box sits on the chosen edge, narrower than the desk, meeting it at one seam line (never a double line); its opening is darker than the desk and open toward the seam; every drawer has exactly one pull, on its outer front; a top or bottom drawer takes 40% of the height, not of the width.
- Drag Light from 1 to 0.72: every fill darkens together toward the line token (never taupe); the ink edge and the ink pull do not change.
- At 8× zoom check the rounded corners, the seam where the drawer meets the desk and the band, and that no contour doubles, steps, or leaves a stub.

## Family

Desk objects

## Docs

- [Desk illustrations guide](https://jbm-ui.bns.studio/docs/desk-components.md)

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [SceneGeometry (scene-geometry)](https://jbm-ui.bns.studio/catalog/scene-geometry.md)

Imported in examples:

- [Ejes (ejes)](https://jbm-ui.bns.studio/catalog/ejes.md)

## 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
