# Design panels and controls

> Pick a panel, button, slider or label in the preview and change it with the Design panel. Every change is written into your project's code.

Source: https://graspable.dev/docs/design

**Design** is an editor for the 2D interfaces inside your 3D scene: panels and the buttons, sliders, toggles, segmented choices, progress bars, labels, dividers, spacers, rows and columns on them. Each interface is shown flat and straight on, like a screen in an interface builder. Click a part, change it in the inspector or ask the agent to change it, and Graspable writes the change into the code that places it. When you go back to the 3D scene or put on a headset, you see the same interface.

Design works with the UI kit that comes with the **Hands & Spatial UI** template. Other web projects, such as Tabletop AR for phones, React XR or a product viewer, can get the same kit: open **Design**, choose **Add the UI kit**, and Graspable puts it in a folder of its own, `ui/`, without touching your files. The agent then adds a first panel to the scene. The kit comes with the Builder plan and higher, like the template.

## Open it

Open a web project and choose **Design** in the header. The window changes for designing:

- **Left:** the scene's interfaces, one per panel, and the parts of the one you are looking at.
- **Middle:** the interface, flat and straight on. **In the scene** shows it where it stands in 3D instead.
- **Right of it:** the inspector for the selected part.
- **Far right:** the agent, as always.

**Back to files**, or **Design** again, closes it and brings back the files and the view you had before.

While Design is open, a click in the preview selects a part instead of pressing it.

## Check it for a device

Under the list of interfaces, **Checks** tells you whether the interface shown can be read and used where it stands. Choose the device above the list:

- **Headset**: whether a finger can reach it (0.35 to 0.7 m away; further away people point and pinch), whether its smallest letters are large enough for their distance, whether its smallest control is big enough for a fingertip (3 cm, better 4 cm) or for pointing from where it is, whether it fits in view without turning the head, and whether it sits between 10° above and 40° below eye level.
- **Phone AR**: the smallest letters and controls in points on a phone screen held upright, against 11 points for text and 44 for a tap.
- **Display glasses**: glasses such as Meta Ray-Ban Display show a 600 × 600 app, not panels placed in a room. Make an app for them from the **Display glasses** template.

Distances are measured from where a person stands when the immersive session starts, eyes 1.6 m above the floor. Click a check to select the part it is about. **Ask the agent to fix it** starts a request with the numbers in it, such as making the smallest text 1.4 cm tall. With more than one problem, **Ask the agent to fix all** sends them in one request.

## Select a part

- Click a part in the flat view or in the scene. It gets an outline, and the inspector shows its settings.
- Or click it in the list of parts on the left.
- **Code** opens the line that places the part.

## Work with the agent

The selected part goes with your next message to the agent, so "make this bigger" or "add a volume slider here" is about that part. The agent's changes show in the flat view as it makes them. Your own edits wait while the agent is working.

## Change it

The inspector shows the settings each kind of part has: a button's label, size and colours; a slider's range and step; a label's letter size, weight and alignment; a panel's title, position and padding. A setting you have not written shows the kit's default in grey.

- Type a value and press Return, or click away.
- Drag left and right on the small mark before a number to change it in steps. The arrow keys step it too, ten steps at a time with Shift.
- In the flat view, drag the small handles on the selected part's right edge, bottom edge or corner to change its width and height. Parts are centred, so they grow on both sides. The preview follows while you drag, and the view keeps still until you let go; the whole drag is one step to undo.
- Select a row, column or panel to see the space between its parts in pink. Drag a pink space to change the gap, or, on a panel, the space at its left, right or bottom edge to change its padding. The new value shows while you drag.
- **×** removes a setting from the code, so the kit's default applies.
- A setting that your code computes, such as a slider's `value={size}`, is shown but not edited here. Change it in the code.

## Theme

With nothing selected, the inspector shows the **Theme**: the colours, spacing and motion that every part of the kit falls back to, from `lib/theme.js`. Change a colour there, such as `accent`, and every slider, toggle and button that uses it changes with it. The note after each value in `lib/theme.js` shows when you point at it.

A colour setting of a part has a **◆** list beside it: choose a theme colour to have the part follow the theme (the code says `color={theme.accent}`), or **Own colour** to give it a colour of its own.

## Motion

Buttons, toggles and sliders move with a spring when they are pressed, pointed at or switched, and a panel comes in with a short movement when it first appears. The inspector's **Motion** section sets both:

- **Spring**: **Quick** (the default for controls), **Gentle** (the default for panels), **Bouncy**, **Slow**, or **None** to move without easing. The curve under the choices shows how the spring settles: Bouncy goes past its end and comes back.
- **Comes in** (for a panel): **Rise**, **Pop**, **Tilt** or **None**. A panel that your code hides and shows again comes in again, so the pages of a menu animate by themselves.
- **Play** shows the selected part's motion again in the preview. It also plays by itself after you change it.
- **Animate on a timeline** opens **Animate** with the part selected, to move, turn, scale or fade it with keyframes, for example a panel that slides in during a film.

The defaults for the whole app are `motion` and `appear` in `lib/theme.js`. Ask the agent for a spring of your own, such as "make the buttons a little bouncier", and it writes `{ duration, bounce }` instead of a name. Projects made before version 0.20.5 have an older kit without springs; the Motion section is not shown for them.

## Add, move and remove parts

- **Add inside** (for a panel, row or column) puts a new part at its end. Graspable adds the import if the file needs one. The parts:
  - **Button**, **Slider** and **Toggle**.
  - **Segmented**: one choice out of a few, side by side, such as modes or tabs. Type its options separated by commas.
  - **Progress**: a bar that fills from 0 to 1, with an optional label and percentage.
  - **Label**: one line of text.
  - **Divider**: a thin line between groups.
  - **Spacer**: empty room.
  - **Row** and **Column**: lay parts out across or down.
- **Add after** puts the new part next to the selected one.
- **Panel beside** (for a panel) adds a second interface next to it, starting with a label.
- Drag a part in the list of parts to move it: onto the top or bottom edge of another part to put it before or after it, onto the middle of a row, column or panel to put it inside.
- **Up** and **Down** swap the part with its neighbour. **Duplicate** copies it, and **Delete** removes it.
- Parts that your code makes in a loop, such as one button per colour, are edited in the code.

## Keys

While Design is open and you are not typing in a field (the keyboard button at the top of the inspector lists them too):

| Key | What it does |
| --- | --- |
| ⌘Z / Ctrl+Z | Undo the last design edit |
| ⇧⌘Z / Ctrl+Y | Redo it |
| Delete or Backspace | Remove the selected part |
| ⌘D / Ctrl+D | Duplicate it |
| ⌥↑ / ⌥↓ (Alt on Windows and Linux) | Move it before or after its neighbour |
| Arrow keys | Move a selected panel by 1 cm, 5 cm with Shift |
| Esc | Clear the selection |

## Use a panel on another platform

A selected panel can be written for other platforms, so one design serves several devices. Under **Use on another platform** in the inspector:

- **SwiftUI** for Apple Vision Pro: a SwiftUI view with stacks, sliders, toggles and buttons, sized so 1 point is 1 mm, on a glass background. Show it in a window or as an attachment in a RealityView.
- **Unity UI Toolkit** for Quest, Android XR and other headsets built with Unity: a UXML file and a USS style sheet. Use them with a UIDocument whose Panel Settings are set to World Space (Unity 6.2 or later), with a scale of 0.001 so 1 pixel is 1 mm.
- **Display glasses** for Meta Ray-Ban Display: a screen of a Display glasses app, built from Meta's Wearables UI toolkit. Glasses have no sliders or switches, so a slider steps with **Less** and **More** buttons, a toggle becomes a button that says its state, and a row of buttons goes to the rail at the bottom.

Choose one to see the code and **Copy** it into a project of that kind. Values that your code computes, such as a slider bound to state, become state of the same name, and what a button does is copied as a comment for you or the agent to connect.

## Undo

**Undo** and **Redo** at the top of the inspector, or the keys above, step through your design edits. Every edit is also a step in the project's **History**, so you can go back further from there.
