Protovibe Studio documentation

A guided tour through Protovibe — from spinning up a project to shipping it to the web.

Creating and running projects

Protovibe Studio is an indy open-source tool that works on your localhost - works on your own computer, withouth a cloud server, without subscription. So you can just ask your AI agent to edit your local files.

In Protovibe your projects is just a folder with code. To start visualy design it you need to run the development server, but you can do it without terminal. Open Protovibe and pick New project. You will be asked for a folder and a project name. Protovibe scaffolds a project template for you.

Once the project is ready, click the "Open Protovibe editor" to start designing. When you're done you can stop the project.

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, 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 multiple or wrap.

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 what is selected on page

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

Adding elements vie 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 frame 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.

Why can't I add an element somewhere?

Sometimes

E does nothing, or "Add element" is not visible. That's because the selected element doesn't have the special markers Protovibe needs to know where a new child can safely be inserted.

Ask your coding agent to "add a pv-editable-zone to this container so I can drop elements inside." Once the zone is there,

E works normally.

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.

Only in code — do it with your AI agent

Ask your coding agent something like "add a new color token called background-accent and wire it through the design system." It'll add the variable to index.css and the matching @theme block. Once that's done, the new token shows up in Protovibe's color pickers and you can edit its value visually like any other.

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.

Only in code — do it with your AI agent

To add a brand-new gradient token, ask your coding agent: "add a new color token called gradient-hero." Once the token exists, return to the Design System tab and edit the gradient stops visually — no code needed for the actual 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.

How to add 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.

What if it's not on Google Fonts?

Custom typefaces from foundries like Pangram or Klim need to be self-hosted. Ask your coding agent to "add a custom font with these .woff2 files and wire it as the primary font" — once it's in the project, it shows up in the font picker like any other.

Working with AI agents

Protovibe works nicely next to AI coding tools. You stay in the canvas designing, and an agent can pick up the same project folder to make code changes you don't want to do by hand.

General advice

Don't edit while the agent is writing

Try not to move or restyle things in the canvas while the agent is mid-task. Both Protovibe and the agent save to the same files, and saving on top of each other can scramble what the agent is writing. Wait until it finishes, then take over.

A few small habits that make agents much more useful:

Use the Prompts panel to copy what you've selected — the agent does much better when it knows exactly which thing on the screen you mean.
Tick "Include Protovibe instructions" if the agent will be writing new layout code, so the canvas can still open it afterwards.
Let the agent finish before you start clicking around. If you really need to step in, stop it first.
If something looks wrong, just press Z. Undo rolls back both your changes and the agent's, so you can always get back to a working state.

Claude Cowork

Yes, you can run Claude Cowork at the same time as Protovibe. Open it on the same project folder and it will see your changes as you make them. It's handy when you want to ask for a tweak in plain English instead of hunting for the right control.

Working in the App tab

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

Double-click to interact

Single click selects an element. Double click interacts with the page — opens menus, follows links, types into inputs.

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.

Traversing the tree instead of layers

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

What is traversing?

Traversing means moving the selection through the element tree with the keyboard instead of clicking. Your page is a nested structure — sections contain rows, rows contain cards, cards contain text. Traversing lets you walk this tree: jump to the parent, dive into a child, hop sideways to the next sibling.

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 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:

Click any Button in the matrix to select it.
In the right panel, find Which state to style and choose size: lg.
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.

In the Sketchpad, build the component visually until you're happy with how it looks.
Select the root element of the design.
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.
Verify the component appears in the Components matrix and works as expected.

Clear context before promoting to a component

Before asking the agent to convert a selection into a component, clear its context (start a fresh thread or use the agent's "new conversation" action). Component extraction is a precise, file-touching task — old context can drag in unrelated assumptions and produce a messier result. Empty context, fresh prompt, clean component.

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.

Styling components that aren't in src/components/ui/

You can still style local components visually — you just need to point Protovibe at the right file. In the right sidebar, find the Source files section and switch between the available files.

There will usually be two: one is the call site (the page where the component is used) and the other is the component definition (the actual component code). Editing styles on the call site changes how the instance looks here; editing the definition changes the component everywhere it's used.

It takes a moment to get used to the file switch, but once it clicks the workflow is fast — and it lets you keep small, page-specific components co-located instead of forcing everything into the global UI folder.

Working in the 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:

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.

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.

Select the element you want to style.
In the inspector, find Which state to style and pick hover.
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.

Responsive design

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:

With no breakpoint selected, set the layout to one column. This is your mobile baseline.
Open Which state to style and pick Screen width above (or whichever breakpoint matches your "tablet up" target).
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. Or just open the preview in a new tab and test in Chrome mobile preview.

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.

For tricky cases where the agent keeps breaking Protovibe rules — wrong block IDs, missing zones, incorrect tokens — tick the "Include Protovibe instructions" checkbox before copying. It will paste the full engineering ruleset into your prompt. Verbose, yes, but it virtually eliminates "the agent removed my pv-block tags" moments.

Publishing to Cloudflare

Protovibe ships your project to the web through Cloudflare Pages. 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.

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).

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

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 React project with real layout, spacing, components, and tokens that someone else can read and use.

And because it's a normal folder of files, you can share it the same way developers already share code — with Git (GitHub, GitLab, etc.) or even just by zipping up the folder and sending it over.

Why this is useful:

A spec that actually runs. Instead of writing a long doc or annotating a Figma frame, you hand over working code. 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.
Real history. If you use Git, every change is saved as a step you can go back to or compare against — handy when you want to show what changed between two designs.
No lock-in. Your project is your project. Protovibe doesn't keep your work hostage — the folder is yours to keep, share, or throw away.

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 colours. The result is a clean, hand-tuned reference that a developer (or their AI agent) can then turn into the real page.

Updating to new version

When a new version of Protovibe is available on GitHub, you will see a prompt in the project manager. From there you can choose whether to update the Protovibe shell across your projects or skip it for now.

If you prefer not to update all projects at once, you can click Update plugin individually per project to pull the latest source from the protovibe-project-template folder. In most cases the easiest path is to tick Update Protovibe shell in all projects — it keeps everything in sync in one step. And if anything looks off, git undo has you covered.

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.

When you undo but it does nothing

Protovibe works on React app Hot Module Reloading. Sometimes this does not work - the file is undone, but you won't see changes. Then just refresh Protovibe app and everything should be back to normal.

When the app crashes

Hit

Z. Because Protovibe writes directly to your files, undo also rolls back the source — so the move that broke the app is reversed and the canvas comes back to life. Keep undoing until you're back to a known-good state.

If undo doesn't help, ask your coding agent. Two prompts that work well: "the app just crashed after I did X — please diagnose and fix," or "I was trying to do X but the editor wouldn't let me — please do it in code." The agent has full access to the source and can usually fix in seconds what the visual editor can't.

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.

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 →

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 →