Collaborate on a design with peers

You and a teammate are working on the same page: you start the landing page, they add the about us page, and both of you want the design to stay in step with the code. Kombai makes that workflow file-based. Each Canvas is stored as a .canvas file inside your project, so you can review and share design work through Git. You can also place comments directly on a design when you need to point to a specific detail.

This guide walks through a collaboration loop: leave focused feedback, share the Canvas on a branch, let a teammate continue the design, and merge the result for the rest of the team.

Before you begin

You need a Kombai project with a Canvas that you want to share. To open an existing one, click Designs below the chat input and select its card in the Canvas Gallery. You can also generate a design with the Design pill selected or create a Canvas manually.

For the recommended team workflow, the project also needs to be in a Git repository that your teammate can access. Kombai stores Canvases under .kombai/canvas/ at the project root. If the work depends on a Design System, keep its .ds file ( ~/.kombai/design-systems/ ) ready as well.

1. Put the design work on its own branch

Create a branch for the design work, just as you would for a feature. Continue designing on the Canvas while that branch is checked out.

Every design in Kombai lives in a Canvas. The Canvas is a project file, so your saved design work appears under .kombai/canvas/. Keeping the canvas containing designs on a branch gives the work its own history and lets the team review it with related changes.

2. Leave feedback on the design

Open the Canvas and click the Comments tool in the bottom toolbar. Then click the exact place on the design where you want to leave feedback, ask a question, or record context for your teammate.

Keep each comment tied to a visible decision. For example, place one on the hero heading and ask, “Can we shorten this to two lines at the desktop width?” Place another on the primary action and note, “Keep this as the strongest visual action in the section.”

3. Commit the Canvas and open a pull request

Stage the relevant changes in the project’s .kombai/ folder, including the .canvas file under .kombai/canvas/. Commit them, push the branch, and open a pull request.

In the pull request description, tell reviewers which Canvas to open and what outcome to check. For example:

Open marketing-page.canvas and review the hero and feature sections. I've also left comments on the designs. Please mark the comment as resolved when you address it.

4. Have your teammate open and continue the Canvas

Your teammate checks out the branch and pulls the changes. They can then open the shared Canvas in either of these ways:

Click the .canvas file in the repository.
Click Designs below the Kombai chat input, then select the Canvas from the Canvas Gallery.

Once the Canvas is open, they can inspect the design for comments, respond to them by asking Kombai to make changes, adding new comments, or resolving existing ones.

If a precise visual adjustment is needed, they can also click Edit in the Canvas bottom toolbar, select the design element, make the change, and click Save.

Once done, they can then commit the updated .canvas file and push it back to the branch.

For a quick, informal handoff, you can share the file directly:

Locate the Canvas under .kombai/canvas/.
Send the .canvas file through your team’s usual file-sharing channel.
Ask your teammate to save it under .kombai/canvas/ in their local copy of the project.
They can then open the Canvas in their Design Mode session.

This transfers the entire Canvas and every design stored in it. It does not include a Design System.

If the Canvas relies on a Design System, locate its .ds file under ~/.kombai/design-systems/ and send that file to your teammate separately. They can save it in their own ~/.kombai/design-systems/ library or anywhere inside their project, where Kombai discovers it automatically.

What this workflow gives your team

You can use the Canvas as a shared artifact where teammates can work on, comment and build collaboratively. Because the canvas is treated as a file that stays in the same repository, its history stays intact.

Next steps

When the design is approved, select it and use Code design in the top toolbar to send it to the agent for code generation.