Protovibe Studio guide & documentation

What is Protovibe?

Protovibe Studio is a free, open-source tool for professional product designers. It works on your own computer — without a cloud server and without a subscription.

The goal is to give you an integrated workspace where you can design alongside your coding agent.

Designing with a coding agent

Protovibe was built for working with AI agents, like Claude Code or Codex.

The basic idea is:
- The coding agent makes major changes to the elements you select
- You tweak paddings, gaps, font colors manually, without prompting

In Protovibe, your project is just a folder of files — HTML, JS, images, etc. When you create a new project, it's stored on your local disk in the /Users/yourname/Protovibe/projects folder. Your coding agent can edit these files directly.

Prototype with Claude Code

1. Install Protovibe and create a new project from scratch. You will get a template boilerplate project with all the basic components. Your coding agent will use it as a foundation and adapt it to your design system.

2. Install Claude Desktop and sign in.

3. Select "Code" at the top of the left sidebar. Note: you need a paid subscription.

4. Click "New".

5. Select your Protovibe project folder — it's under /Users/yourname/Protovibe/projects/your-project-name/

6. Switch Claude to "Auto" mode, select the Opus model, and set the effort level to Medium.

7. Send your coding agent a message describing what you want to do in your project — for example, a screenshot of what you want to build. You can ask it to rewrite the whole project, adapt the design system, etc.

8. When the agent has finished its changes, you can tweak the design manually in the Protovibe editor, or keep iterating with Claude.

Prompts and context

When you ask your coding agent to do something, it works better with context — knowing which element you mean, what file it lives in, and what the surrounding code looks like.

The Prompts panel lets you copy the context of any selection straight into your clipboard. Pick the elements you want to discuss, hit copy, paste into your agent. The agent now knows exactly which nodes you're talking about.

Navigating the prototype in the editor

The App tab shows your live application exactly as users will see it. There is one rule that surprises everyone on day one:

This is the opposite of a normal browser, but it lets you select things through interactive widgets. Want to style a button? Click it once. Want to actually press it and see what happens? Double click.

Keyboard shortcuts

Once you get used to these shortcuts, designing in Protovibe starts to feel like playing a video game — you can add, traverse, and delete elements without ever touching the mouse.

Classic shortcuts

Z

Z — undo and redo. Protovibe is editing real files, so undo also rolls back the source.

C

V

X — copy, paste, or cut the selected element. Paste drops the element inside the current selection.

V — paste after the selected element (as the next sibling). Useful when you want the new element next to the current one rather than inside it.

D — duplicate the selection in place.

Backspace — delete the selected element.

Click — multi-select elements to delete or wrap them together.

A — wrap the selected elements into a new container. Select multiple elements first with

Click, then press

A to group them inside a fresh div.

[ ] — move the selected element up or down among its siblings.

Space (hold) — pan the canvas in the Sketchpad.

Navigating the selection

W A S D — move the selection through the element tree: parent, child, previous, and next.

Adding elements with keyboard shortcuts

E — open Add element to insert a new element inside the current selection. Only works when the selected element is a container that allows children (see the note below).

E — Add element after: insert a new element as the next sibling of the current selection. The fastest way to chain new items in a list or row.

Traversing elements

Once something is selected, you almost never need the mouse to navigate. Use W A S D to walk through the element tree:

• W — go up to the parent (the container that wraps the current element).
• S — go down into the first child.
• A / D — move to the previous or next sibling at the same level.

Example: you've selected a piece of text inside a card. Press W to jump to the card itself. Press D to hop to the next card in the row. Press S to dive into that card's content. It is much faster than aiming with the cursor, especially in dense layouts.

Styling individual elements

Select any element on the canvas and the right inspector opens with everything you can change — layout, spacing, typography, colors, borders, effects. Drag the values, type in numbers, or pick tokens from the dropdown.

When the inspector doesn't have what you need

The inspector intentionally doesn't expose every CSS property. Instead of cluttering the UI with rare features (clip-path, animation timing functions, blend modes…), Protovibe leaves them to your coding agent. Just describe what you want — "make this button shimmer on hover" — and the agent will write the styles for you. You don't need to know the CSS.

The applied classes list

At the bottom of the inspector you'll see the list of classes currently applied to the element. It's the source of truth for what's actually on the DOM. Use it for two things: debugging ("why does this look weird?" — read the classes), and surgical tweaks the visual fields don't cover (you can edit the string directly).

Open in VS Code

Every element header has an Open in VS Code button. It jumps your editor straight to the line of source for the selected element. Most days you won't need it — but when the visual editor gets stuck on something unusual (a tricky conditional, an exotic component), opening the file and editing it directly is always the escape hatch.

Styling hover

By default, anything you change in the inspector applies to the resting state. To style what happens on hover, switch the state first.

1. Select the element you want to style.
2. In the inspector, find Which state to style and pick hover.
3. Change any style — background, text color, shadow, scale. The new values only apply when the cursor is over the element.

To preview the hover, just move your cursor over the element on the canvas.

How to add tooltips

Tooltips are a single field in the inspector sidebar — there's no special component to wrap things in. Select any element, find the Tooltip field, and type the text you want to appear on hover. That's it.

Clear the field to remove the tooltip. The tooltip styling matches your design system automatically.

Adding images

There are two ways to drop an image onto the canvas, and both end up the same way: as a background image on the selected element.

• From the inspector — open the Background image field in the sidebar and pick a file.
• Paste from clipboard — copy any image (a screenshot, a Figma frame, a PNG from your browser) and hit
  V on the canvas. Protovibe compresses the image automatically and applies it as a background.

By default, Protovibe sets the size mode to Fit and matches the element's aspect ratio to the image — so it shows the whole picture without cropping or distortion. That's almost always what you want for hero shots, screenshots, and product images.

Need something different? Switch the size mode to Cover for a fill-the-frame look (the image will be cropped to fit), or set the aspect ratio manually in the Size panel for full control over the container's shape.

Mobile preview (RWD)

Protovibe is built on Tailwind, which is mobile-first. That means the styles you set with no breakpoint apply to every screen size, including the smallest. Bigger screens then layer on top.

Concretely, to make a grid that's one column on mobile and three columns on desktop:

1. With no breakpoint selected, set the layout to one column. This is your mobile baseline.
2. Open Which state to style and pick Screen width above (or whichever breakpoint matches your "tablet up" target).
3. Now change the layout to three columns. This override only kicks in above that width.

To preview the small-screen result, click the Mobile preview button above the page. The canvas resizes to a phone-width frame so you can verify the mobile layout without resizing the window. You can also open the preview in a new tab and test it with Chrome's mobile preview.

Sketchpad

The Sketchpad is the free-form canvas — closer to Figma than to a browser. Selection rules here are flipped to match what classic design tools do:

Use Sketchpad to quickly explore some layouts so you can make a screenshot for your AI agent to rebuild it. Or actually design something by hand and point your coding agent to reuse this in the main App prototype.

• Single click selects the top-level frame. Double click drills one level deeper into a child.
• Hold
  and click to jump straight to the deepest element under the cursor — no double-click chain needed.
• Hold Space to pan the canvas with the mouse.
• Drag a marquee across empty space to multi-select everything inside the rectangle.
• Hold
  (Option / Alt) and drag a selection to duplicate it. The new copy follows the cursor.

Adjusting the design system

Open the Design System tab to edit your color tokens, radii, fonts, and spacing scale. Changes flow through every component instantly — there are no styles to "republish".

Editing colors

Each color is a semantic token — for example background-primary or foreground-secondary. Click any swatch to change its value. The whole app picks up the new color in place because every component refers to the token, not a raw hex.

Protovibe ships with most of the tokens you'll need out of the box — backgrounds, foregrounds, borders, primary/destructive/warning roles, and a few hover/active variants. For most projects you'll just retune the values, not add new ones.

Light and dark mode

Every token has a light and dark value, so you design the app in both modes at the same time. Flip between them any time using the mode toggle in the bottom left — it switches both the app preview and the components grid.

How to add new colors?

The Design System tab lets you edit existing tokens, but it can't yet create new ones from scratch. Tokens live in your project's CSS file as variables, and adding a new one means writing a small piece of code.

How to create gradients?

Gradients are stored as a special kind of color token: any token whose name starts with gradient- (for example gradient-hero) is treated as a gradient instead of a flat color. Protovibe automatically switches the swatch editor into gradient mode for those, letting you pick stops, direction, and opacity visually.

Once saved, the gradient appears in any background-color picker just like a normal token. The prefix is the only thing that distinguishes gradients from solid colors.

Adjusting shadows

Shadow tokens (shadow-sm, shadow-md, shadow-lg, …) work the same way as colors — edit one, and every component using it updates. Click any shadow swatch to open Protovibe's built-in shadow editor.

Instead of fiddling with a single blur and offset, the editor lets you stack multiple soft layers — exactly the trick designers use to get those expensive-looking, smooth shadows you see on premium product sites. Tune layer color, opacity, blur, spread, and vertical offset for each, and preview the result live as you drag.

Tip: a beautiful shadow almost always combines a tight, dark layer for contact with a wider, fainter layer for ambient light. Start there and adjust to taste.

Editing other tokens

The Design System tab also exposes the rest of your visual scale — and they all work the same way: edit a value, and the whole app updates wherever the token is used.

• Font size — the typography scale (text-sm, text-base, text-lg, headings…). Retune the steps to make your app feel tighter or more airy across the board.
• Letter spacing — tracking values used by display headings, all-caps labels, and body text.
• Line height — the leading scale that controls vertical rhythm for paragraphs and headings.
• Border radius — corner roundness from rounded-sm up to rounded-full. One of the strongest brand-shaping levers.
• Spacing — the base spacing unit that drives padding, margin, and gap utilities everywhere.
• Fonts — the primary and secondary typeface families used by your app.

Adding a custom font

The font picker shows a curated list of the most common Google Fonts so you can scroll, preview, and pick. If the font you want isn't in the list, don't worry — the picker also accepts any Google Font name typed in directly. Paste the exact name (for example Fraunces or Bricolage Grotesque) and Protovibe will load it for you.

Styling components

Components like Button or Card are the reusable building blocks of your app. To edit one, open the Components tab and pick it from the list.

The components matrix

Each component opens into a matrix — every meaningful combination of its props rendered side by side. So a Button matrix shows solid / ghost × small / medium / large × enabled / disabled in a single grid. It's both a preview and a sanity check: if one cell looks wrong, you can spot it immediately.

Hiding combinations that don't make sense

Some prop combinations are nonsense — an "icon-only" button with no icon picked, for example. Those are filtered out by a small list called invalidCombinations in the component file. It's just a list of "if these props are set this way, don't render this cell." If you ever notice the matrix showing a broken state that you want hidden, ask your coding agent to "add it to invalidCombinations" and it'll disappear from the preview.

"Which state to style"

This is the most important control in the components view. By default, any change you make applies to every variant of the component. That's usually what you want — give every Button the same border radius.

But sometimes you want a change to only apply to one specific state. To style a large button without touching the small or medium ones:

1. Click any Button in the matrix to select it.
2. In the right panel, find Which state to style and choose size: lg.
3. Edit styles. The new values will only apply when size is lg; the rest of the matrix stays untouched.

What does "Unset" mean?

Most style fields have an Unset option. Picking it doesn't mean "set to zero" or "set to default" — it means don't add a style for this property at all. The element keeps whatever it inherits from the default variant (or from the browser, if there's nothing else).

Use Unset when you want a variant to fall back to the base. For example: a large button might override the padding, but you'd Unset its background color so it shares the same color as small and medium.

Creating new components

In a traditional design tool, building reusable components means planning a system upfront — naming things, defining variants, locking in a structure. With AI in the loop you don't need any of that. Start messy, then promote things to components when a pattern shows up. Below are the three workflows that work best.

Sketch first, then convert

This is the smoothest path for components with a clear visual identity (cards, badges, callouts). Design the basic shape in the Sketchpad first — drop in raw elements, get the layout, colors, and proportions right. Don't worry about props or reusability yet.

1. In the Sketchpad, build the component visually until you're happy with how it looks.
2. Select the root element of the design.
3. Open the Prompts tab and ask the coding agent to "convert this selection into a reusable component." It'll extract the JSX, decide which props to expose, and register a pvConfig so the component shows up in the Components list.
4. Verify the component appears in the Components matrix and works as expected.

Ask AI to scaffold a component, then style

When you know roughly what the component should be ("a stat card with an icon, label, value, and trend"), skip the sketch and ask the agent directly. It'll create the file, register the pvConfig, and seed sensible defaults. Once the component exists, drop it onto a page and tune the styling visually in the inspector and the components matrix.

Build the page first, extract components later

This is the workflow that breaks the most with classic design tools — and the one AI makes effortless. Just build the page with raw, duplicated blocks. Three feature cards? Copy-paste the same div three times and edit the contents. Don't plan, don't extract, don't think about reusability.

Later, when the page feels right, select the section containing the duplicates and ask the agent: "extract the repeated cards in this section into a reusable component." It'll find the pattern, build the component, and replace the duplicates with instances — all while keeping the page visually identical.

The big shift: components stop being something you plan, and start being something you notice after the fact. Build first, abstract later — the agent handles the refactor.

Where do components live?

Protovibe only scans the src/components/ui/ folder for reusable components. Anything in there shows up in the Components tab, the components matrix, and the "Add element" picker. If your coding agent saves a component anywhere else (a local helper next to a page, for example), it won't appear in those places.

That's not always a bug. Local components — small bits of JSX you only use on one page — are often cleaner kept next to the page that uses them. They don't pollute the global components list, and they keep the page file readable. If a component is only ever going to live on the dashboard, it can stay in Dashboard.tsx.

Publishing and sharing your prototype

Protovibe does not store your project on servers. Instead, it gives you a one-click flow to publish your app to robust, free hosting on Cloudflare. The first time you click Publish, you'll be asked to log in to your Cloudflare account — this is a one-time setup and your credentials stay on your machine.

After the first successful publish you'll get a live URL. Subsequent publishes update the same site in seconds.

Hand-off: writing specs and annotations

Use the "Specs" tab to write walkthroughs and annotations for your prototype. They're published together with your prototype, so you can send them out to your team.
1. Select an element in the app.
2. Add an annotation.
3. Write it as you would in Notion or any other document editor.
4. Publish your prototype and send the "Specs" link to your developers.

Collaboration

Protovibe is a place to design — not where your team's real production app lives. Think of what you build here as a very precise, working reference: a web project with real layout, spacing, components, and tokens that someone else can read and use.

Protovibe simplifies the Git workflow to a single "Sync with git" button. Once you're logged in to your Git account, just use this button at the bottom of your screen.

Ask your coding agent to help you log in to GitHub from your terminal app, or log in to GitHub via the "Connect to GitHub" button. The latter may not work for company repositories owned by your organization — for those, it's better to log in from the terminal using the GitHub CLI (ask your coding agent to guide you).

Benefits of collaborating via Protovibe

• A spec that is a real web app. Instead of writing a long doc or annotating a Figma frame, you hand over working code with annotations baked in. There's no "did I describe this padding correctly?" — it's right there.
• A perfect input for AI agents. A developer's AI agent can read your Protovibe code directly. That's far more precise than any written spec — the agent sees the exact components, classes, and structure you intended.
• No vendor lock-in. Your project is your project. Protovibe doesn't keep your work hostage — the folder is yours to keep, share, or throw away.

Comments

Protovibe has a built-in place to leave comments. Comments are stored as files in your Git repository.

Otherwise, comments work much like they do in Figma — you can attach a comment to a prototype URL and an element, and there are threads, unread counts, etc.

Working with UX writing & copy

Your UX writer can use Protovibe to suggest copy changes directly from comments. The suggested copy is highlighted on canvas so you can see the suggestion and accept it or discuss it in a comment thread. Your coding agent can apply accepted suggestions for you, so you don't need to make the changes manually.

Use case: handing a design to a developer

You design a screen in Protovibe and share the folder with a developer. They don't have to copy your work into their real codebase by hand — they point their AI agent at your Protovibe project and say "build this in our app, matching the layout and spacing." The agent has the actual code in front of it, so the result is much closer to what you drew than a written brief would ever get.

Use case: marketing and designer working together

Someone in marketing sketches a landing page in Protovibe and shares the folder. A designer opens the same project and polishes it by hand — nudging paddings, fixing border radius, swapping a font weight, tweaking colors. The result is a clean, hand-tuned reference that a developer (or their AI agent) can then turn into the real page.

Troubleshooting

Protovibe edits real source code, so the occasional weird state is expected — a half-applied change, a component that won't render, a canvas that's gone blank. Here's the order to try things in.

Reporting bugs

We're an indie team of just a few people, so bugs do slip through. If you hit one we'd love to hear about it — a quick description (what you were doing, what happened, what you expected) is enough to get us started.

• Email us at protovibe.studio@gmail.com.
• Or open an issue on GitHub.

Thank you for your patience while we polish things.

FAQ

Why do I need to "run" and "stop" projects?

When you open a project, you need to click the "Run project" button. This starts the whole development environment for you, so you can preview your website in your own browser at localhost:3000. Developers normally do this from a terminal app (command-line interface), but with Protovibe you just hit a button.

Can I use Protovibe for landing pages?

Yes! Actually this landing page you see now is made in Protovibe. Just ask your coding agent to make a landing page, but still use the design system and components from the default project template.

Under the hood (for the curious)

You don't need any of this to use Protovibe — but if you ever open a source file you'll see two unfamiliar things.

pv-editable-zone and pv-block comments. These are markers Protovibe writes around every reorderable element. They tell the canvas which JSX nodes are independent units and which container they belong to. Without them, the visual editor wouldn't know how to cut, copy, or move things.

pvConfig exports. Each reusable component has a small config object describing its props, default content, and how it should appear in the components matrix. This is what powers the inspector and the matrix preview.

The full ruleset for both lives in PROTOVIBE_AGENTS.md on GitHub. If you ever ask a coding agent to scaffold or refactor a component, point it at that file — it's the canonical reference. Read PROTOVIBE_AGENTS.md →

Behind the scenes Protovibe runs Cloudflare's wrangler command in a background terminal. You don't have to interact with it, but if a publish fails the terminal log shows up in the Project Manager so you can see what went wrong (or paste it to your coding agent for help).

Open-source license

Protovibe is free to use for building and exporting your own projects — personal, commercial, client work, all of it. The code you create is yours.

The one thing you can't do is embed the Protovibe editor itself inside a commercial web-builder product. If that's what you're after, get in touch about a commercial license at protovibe.studio@gmail.com.

Read the full license on GitHub →