# Calvin Usage Guide for VTEX IO

### Configuration Steps

{% stepper %}
{% step %}

#### Create a Workspace in VTEX IO

The first step is to create a workspace within Calvin for VTEX IO. Depending on what you want to build, you must choose between:

* VTEX Store Theme workspace
* VTEX Custom App workspace
* VTEX Admin workspace

Make sure to select the option that matches your project type.

<figure><img src="https://709796108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpZ0EFvUFT8BuQyvFC2E%2Fuploads%2FNdAthixyf7WyjqXwimlN%2Funknown.png?alt=media&#x26;token=046aba3d-66fd-4d99-9a84-988e58d88c31" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

#### Connect a Project or Template

Once the workspace is created, you have two options: use our VTEX template or connect to an existing repository. In either case, navigate to settings by clicking the Settings button.

<figure><img src="https://709796108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpZ0EFvUFT8BuQyvFC2E%2Fuploads%2FzMSgDXaS0h0KgvoM0Ni9%2FCaptura%20de%20pantalla%202026-03-27%20a%20la(s)%2012.23.28%E2%80%AFp.%C2%A0m..png?alt=media&#x26;token=2818bd28-f98d-4f43-bb1f-68b4d1ef847d" alt=""><figcaption></figcaption></figure>

**Use a Template**

You can create a new project from a base template. To do so, click the 'Use template' button and wait for the template to be added

**Connect to an Existing Repository**

To connect Calvin to an existing repository:

1. Navigate to the 'Repository' folder on settings.

<figure><img src="https://709796108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpZ0EFvUFT8BuQyvFC2E%2Fuploads%2FmtEI2zOeRkBFVDIVUr8w%2FCaptura%20de%20pantalla%202026-03-27%20a%20la(s)%2012.34.21%E2%80%AFp.%C2%A0m..png?alt=media&#x26;token=ecadf1d1-4d45-40aa-a077-4b1d771b9319" alt=""><figcaption></figcaption></figure>

2. Select the option to connect to a repository and complete all required fields:

* GitHub
* Bitbucket
* GitLab

3. Choose the branch you want to work with.
4. In the settings section, define the behavior when a chat is completed:
   * Automatically merge into the selected branch
   * Create a Pull Request to the selected branch

{% hint style="info" %}
This configuration determines how Calvin will handle the code changes generated when a chat is completed.
{% endhint %}

{% endstep %}

{% step %}

#### Select the Correct Documentation

Inside Calvin’s settings, on the 'Repository' folder, you must select the type of documentation you will be working with.

Available options:

* VTEX IO
* VTEX Admin
* VTEX Custom App

It is important to select the option that corresponds to the type of workspace you previously selected.

{% endstep %}

{% step %}

#### Perform the First VTEX Link

After configuring the repository, it is necessary to run a VTEX link to your previously created VTEX IO workspace.

To do this:

1. Click the 'Settings' button
2. Navigate to the 'VTEX IO' folder

<figure><img src="https://709796108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpZ0EFvUFT8BuQyvFC2E%2Fuploads%2F0BgAvLwUui8kRq8diFAu%2FCaptura%20de%20pantalla%202026-03-27%20a%20la(s)%2012.42.06%E2%80%AFp.%C2%A0m..png?alt=media&#x26;token=d50ca0ec-e53b-4041-9fef-5b26d8d94474" alt=""><figcaption></figcaption></figure>

3. Complete the required fields.
4. Execute the link process.

**Link Verification**

It is recommended to verify that the process was completed successfully:

1. Click the 'Settings' button
2. Navigate to the 'Sandbox' folder

<figure><img src="https://709796108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpZ0EFvUFT8BuQyvFC2E%2Fuploads%2FLL0noN0EnITMQNIXVq2I%2FCaptura%20de%20pantalla%202026-03-27%20a%20la(s)%2012.45.04%E2%80%AFp.%C2%A0m..png?alt=media&#x26;token=4a8705b5-81fc-4fa4-bdde-36cc270d4cab" alt=""><figcaption></figcaption></figure>

3. Check that there are no compilation errors

{% hint style="info" %}
This initial link is essential because it allows Calvin to recompile the project and validate that generated changes do not contain errors.
{% endhint %}
{% endstep %}

{% step %}

#### Using Calvin in the Project

Once all previous steps are completed, Calvin is ready to be used in your VTEX IO project.
{% endstep %}
{% endstepper %}

***

### Suggestion for Pixel Perfect Implementation

To request a pixel perfect component implementation from Calvin, it is recommended to follow this workflow:

1. Attach the HTML file containing the component design. This HTML can be extracted from the UI/UX workspace. For more information on how to do this, see the UI/UX workspace documentation.
2. Include a base prompt adapted to the component you want to develop.

#### Recommended Prompt

```
Create a pixel perfect implementation of the following <component>, 
the design must be pixel perfect with the html file.

Requirements:
- Examine the html file “<html file>”
- Study the existing design implementation in detail
- Ensure pixel perfect accuracy to the original design
- Don’t use Tailwind to make the implementation
- It’s important that you use the exact same SVGs used on the html file
- Study the current implementation before starting, you can find it on <VTEX workspace URL>
- To check it after a change, you must restart the vtex link and probably reload the page of the url
```

This prompt can be adapted and expanded according to the project’s needs by adding additional requirements or specific instructions.

***

### Recommendations

* Always check the logs after each VTEX link.
* Visually review the generated implementations before completing a chat.
* Use clear and specific prompts for better results.
* When developing something complex, better and faster results are usually achieved by dividing the work into smaller, manageable parts. Instead of requesting everything in a single prompt, it is recommended to modularize what you want to achieve. For example, you can first ask Calvin to build only the base structure of the component, ensuring that all elements are correctly organized and positioned. Once that structure is validated, you can then request the pixel perfect design, adjusting styles, spacing, typography, and visual details.