# Design

Have an agent draw your screens before anything is built, change them by pointing at them, then hand them to a build task.



A design task draws screens before any code is written: wireframes or high fidelity, at desktop, tablet and phone size, in your type and colours. You look at them on a canvas, point at what's wrong, and when they're right you hand them to a build task, which is told whenever the design changes afterwards.

The screens are ordinary HTML files in the task's branch, so they're reviewed, kept and landed like any other work.

## Start a design task [#start-a-design-task]

Open the **Design** tab in the workspace. If the task in the chat has no design yet, the tab offers **Design it before you build it**: describe what to design ("a checkout with a summary and one Pay button"), pick the agent and press **Start a design task** (<Keys k="Mod+Enter" />). You can also choose **Design** on the **Start another lane alongside** card at the end of the **Tasks** tab.

A design task is a task like any other, with its own branch and chat. Before its first turn the agent is told how to lay the screens out so Styx can show them.

## The canvas [#the-canvas]

<Shot src="/docs/img/design.jpg" alt="The Design tab: a Checkout screen at desktop, tablet and phone size side by side, the Pay button selected, and an inspector with Text, Fill, Colour, Type and Corners above a Tell Codex box" caption="A checkout design at three sizes, with the Pay button selected" />

The toolbar runs along the top:

* **Wireframe**, **Hi-fi** and **Both** choose which passes to show (Both is the default, so a wireframe sits beside its hi-fi). Wireframes are greys, boxes and placeholder text; hi-fi is the real thing.
* **All sizes**, **Desktop**, **Tablet** and **Phone** choose which sizes to show. Desktop is 1280 pixels wide, tablet 834 and phone 390. Hiding a pass or a size leaves the other boards where they are.
* The arrow is **Select** (press <Keys k="V" />).
* **Aa** opens **Type and colour**.
* **Zoom to fit**, **Tidy up**, the zoom control (**−**, the percentage, **+**), and **Build it** at the right.

The list on the left holds the design's **Screens**; clicking one zooms to its boards. **+ Ask for a screen** takes a name and asks the agent to design it. With nothing drawn yet, ask the agent in the chat for a screen, as a wireframe or high fidelity. While the Design tab is open, the project nav steps aside to give the canvas room.

## Move around the canvas [#move-around-the-canvas]

The canvas is a freeform surface: the screens sit on it as boards you can zoom into, move around and arrange.

* **Zoom** toward the pointer: pinch on a trackpad, or hold <Keys k="Mod" /> and scroll the mouse wheel. <Keys k="Mod+=" /> and <Keys k="Mod+-" /> step in and out, <Keys k="Mod+0" /> zooms to fit, and with the canvas focused <Keys k="Mod+1" /> goes to 100%. Zoom runs from 10% to 400%.
* **Pan** by scrolling with two fingers or the mouse wheel (hold <Keys k="Shift" /> to scroll sideways), by dragging the empty canvas, by holding <Keys k="Space" /> and dragging, or by dragging with the middle mouse button.
* **Move a board** by dragging its name above it. Boards snap to an 8 pixel grid. Tab to a board's name and the arrow keys move it 8 pixels (40 with <Keys k="Shift" />). <Keys k="Mod+Z" /> undoes the last move.
* **Tidy up** puts every board back in rows, one row per screen with its sizes and passes side by side, and offers **Undo**.

The first time you open a design, it's laid out in those rows. Once you move something, the arrangement is saved in `.styx/designs/canvas.json` beside the screens, so it's committed and landed with them and a teammate opens the same layout. When the agent draws a new screen or size later, it's placed beside the others without covering anything, and a note offers **Show it**. Zoom and pan are yours alone: they aren't saved to the project.

## Change a screen by pointing at it [#change-a-screen-by-pointing-at-it]

Press <Keys k="V" />, or the arrow, and then either click an element or drag across an area of a screen: a section, part of one, or across several elements. This works at any zoom; to pan while Select is on, hold <Keys k="Space" /> or use the middle button. <Keys k="Esc" /> clears the selection.

With one element selected, the inspector on the right lets you change it by hand: its **Text**, **Fill**, **Colour**, **Type** and **Corners**. The change is saved to the screen's file straight away.

Or describe the change: type it in the **Tell** box (it carries the agent's name, as in **Tell Codex**) and press **Send to Codex** (<Keys k="Mod+Enter" />). The agent gets the screen, the element you picked and a picture of it, and the chat shows a small chip naming what you pointed at. This works for an area too, which is often easier than describing where something is.

## Type and colour [#type-and-colour]

**Aa** opens the design's tokens: **Colours**, **Typefaces** (headings and body), the **Type scale**, **Corners** and **Spacing**. A change here applies to every screen at once. These are saved as the design's tokens, and the build task uses them as the app's own. If the design has none yet, **Use these** gives you a starting set to change, or you can ask the agent to set them.

## Build it [#build-it]

When the screens are right, press **Build it**. You choose:

* **New build task**: a new lane branched from the design, with the agent you pick. Styx commits the design files first, so the build starts with them.
* **Build here**: the design task carries on and builds it itself.

You can add a note for the build ("use our Button component"), then press **Start building**. The build task's first message names the screens and where they are, asks it to match each size that was drawn in the app's own stack and components, and to use the design's colours, type, corners and spacing as the app's tokens.

The two tasks stay linked. Their cards on the Tasks tab name each other ("From design", "Being built by"), and the build task's Design tab shows the design's screens. When the design changes afterwards (a hand edit, a change to Type and colour, or a design turn that redraws a screen), Styx commits it in the design task's branch and tells each build task what changed and how to bring it in (a `git merge` of the design branch, which only touches `.styx/designs`). The design task's chat notes that the build task was told.

In [Preview](/docs/using/preview), **Select to fix** on the running app can send a problem back to the design task instead, when it's a design problem rather than a bug.

## Designs are files [#designs-are-files]

Everything lives in the task's worktree under `.styx/designs/`:

```text
.styx/designs/
  tokens.json            colours, typefaces, type scale, corners, spacing
  tokens.css             written by Styx from tokens.json
  canvas.json            where the boards sit, once you've moved one
  checkout/
    desktop.html         hi-fi, 1280 px
    phone.html           hi-fi, 390 px
    desktop.wire.html    wireframe
```

Each screen is a single self-contained HTML file that uses the variables in `tokens.css`. You can open them in a browser, and any agent can read them.

A build task that has screens of its own under `.styx/designs/`, such as a mockup you dropped in, shows them on its Design tab too, and new files appear without a reload. **Build it** is hidden there, since that task already is the build.

<Callout type="note">
  Screens on the canvas never run code: scripts are stripped, links don't navigate, and the frames can't load
  anything from the network. That keeps a design file from doing anything inside Styx, and it means
  interactive behaviour belongs in the build, not the design.
</Callout>

For a worked example from first sketch to running app, see [Design, then build](/docs/guides/design-then-build).
