Yard Docs
Sign in
On this page

Tips

Get better results from Yard's agents and keep a canvas easy to work with: selecting context, sheets, the design system, short specs and more.

Updated November 11, 2026 · 3 min read

Give the agent the design system

An agent builds UI the way you show it. Keep the design system on a sheet: a note listing the components and when to use them, a screenshot of the colour and spacing tokens, and a link to the live component catalogue (Yard's own is at /design-system). Drag the sheet in when you start UI work, and say "use the components in the design system sheet" in the prompt.

Point at the exact thing

The less the agent has to guess, the better the result:

  • A repository: select its block to give the agent the whole repository.
  • Some lines: highlight them in the repository explorer and add a note saying what is wrong with them.
  • One file: extract it onto a canvas as a block and select only that.
  • In writing: type @ in a project's spec to mention a block, a file or a repository.
  • By dragging: drop a block, a sidebar row or a file onto the chat's message box to add it as context for the next message.

See pointing an agent at blocks.

Keep what is always true at hand

Nothing goes with a message unless you select it. Pin the blocks you reach for every time (the product brief, conventions, the design system) to your sidebar. A pin does not go with a message by itself: type @ in the work composer and your pins come first, under Pinned, or drag one from the sidebar onto it. A pin whose doc or block was archived or deleted is neither counted nor offered: it waits, muted, in the Pinned section of the workspace overview until you unpin it.

Frame by piece of work

Gather everything about one feature (the note, mockups, research links) into a frame. Selecting the frame selects all of it, it moves as one, and the canvas stays readable as it grows. ⌘/Ctrl+G frames the selection.

Keep specs short and checkable

A good spec is a goal in a sentence or two and acceptance criteria that can each be checked: "Delete can be undone for 8 seconds", not "Deleting should feel safe". The agent ticks the criteria off as it meets them, so you see progress against what you asked for. Mark what matters: (must) for what cannot ship without, (nice) for what may stay open, and group them under ### areas with #tags (see areas, priorities and tags): only open must-haves hold up the merge. Its own steps go in .yard/progress.md, not in the spec: write the Plan as numbered steps, grouped into ### Phase N: <title> sections for bigger work, and the agent's progress file (and its commits, one per phase) follows them. To change what it does next, edit that file in the project's terminal or ask in the chat.

A project or a chat beside a doc?

  • Ask in the chat beside a doc or sheet to explain or summarise it.
  • Start a project for anything else: it gets its own directory, and when it builds something, its own container and branches, ending in pull requests or files.

Answer questions quickly

When an agent is missing context it stops and asks, and the project shows Needs input. You are notified; answering in the project's chat lets it carry on.

Long chat? Compact it

When a chat has grown long, type /compact: the agent summarises the conversation and you carry on in a fresh chat that starts from the summary.

Let history be your undo

Everything in docs, on canvases, in notes and in specs is saved with history. Rearrange freely: you can see who changed what and revert from history.

Was this page useful?
Edit this page