Style-first AI workshop — setup guide

Build one landing page of your choice, starting with the visual style of one existing page. Choose any subject—a business, product, event, portfolio, service, or hobby—and use your preferred AI coding assistant. No professional coding experience is required.

One homepage, not a whole website: use the reference for typography, colours, spacing, and layout. Do not copy its sitemap or build its About, Pricing, Blog, or other pages. Your navigation will link to sections on your own landing page.

Total setup time: allow about 60–75 minutes, including downloads and a full project check. Complete it at least one day before the workshop if you can. If you hit a snag, send Big Chris the step number and the exact error message.

Don't stress if setup takes longer than expected. Developer tooling can be fiddly even for experienced engineers. The workshop is designed so people can catch up during exercises, and Big Chris will help troubleshoot.

The important finish line: do not stop after installing the tools. After Step 10, give your AI the project handover. In Step 11 it will install the project dependencies, run the checks, and give you a preview link to open. That final check is what proves you are ready.

Start here: follow the numbered steps in order

Begin with Step 1 and complete each “You're done” check before moving to the next step. Even if you already have some tools installed, verify them when their step appears. Do not open several installer links and work through them in a different order.

Every download link appears in the step where it is needed. A reference list is at the very end of this guide, after the checklist.

About your choice of AI assistant

This workshop is AI-tool agnostic. Choose Claude Code or Codex inside VS Code, or use Antigravity IDE with its built-in assistant.

Antigravity users: wherever later steps say “VS Code”, use Antigravity IDE instead. Keep the project and assistant in that same editor; let the assistant handle terminal work.

Your assistant needs to be able to:

• read and edit files in the project you have open in your editor;
• run terminal commands after asking your permission; and
• read the workshop's project-instructions file when you ask it to.

Steps 1–3 walk you through VS Code and your chosen assistant before you are expected to use it. If you are unsure which assistant or account to use, ask Big Chris before the workshop.

The shared rulebook is WORKSHOP.md. Claude Code, Codex, and Antigravity all use the same one-page exercise and teaching instructions. Their entry files point to it; if your assistant does not load it automatically, ask it to read WORKSHOP.md and WORKSHOP-SETUP-AGENT.md.

Minimum requirements

Recommended:

• macOS 13+ or Windows 11 (older versions usually work but are not guaranteed)
• 8 GB RAM minimum (16 GB preferred)
• 10 GB free disk space
• Reliable internet connection
• Admin access on your machine so you can install software
• Access to your chosen AI coding assistant

Corporate laptop warning: some work machines block developer tools, AI assistants, or VS Code extensions through IT policy. Do setup at least a day before the workshop so there is time to request access or arrange another device.

What you're going to install

By the end of setup, you'll have:

This guide does not require or recommend a particular commercial AI subscription. Confirm your assistant's access, usage limits, and costs with its provider or your organisation before the workshop.

A note on package managers (Mac users especially)

If you're already comfortable with Homebrew, Chocolatey, Scoop, or NVM, use what you prefer.

Otherwise, please use the official installers linked in this guide. Mixed package-manager installations are a common cause of “command not found” or “wrong version” problems during workshops. Standardising on the official installers makes troubleshooting much faster.

Step 1 — Install and open Visual Studio Code (5–10 minutes)

Using Antigravity? You do not need a separate VS Code installation. Continue to Step 2 and choose Route C; its editor installation is included there.

We mean Visual Studio Code, also called VS Code, with the blue ribbon-shaped icon. Visual Studio is a different application. You do not need to open PowerShell or type any commands during Steps 1–3.

Download VS Code for your operating system from https://code.visualstudio.com/download and install it:

• Windows: use the User Installer and keep Add to PATH selected.
• Mac: open the .dmg download and drag Visual Studio Code into Applications.

Windows users: the big blue Windows button downloads the User Installer. Mac users: the Mac button downloads the .dmg; choose Apple silicon or Intel chip if asked. Ignore the Linux column.

Already installed? Open it and continue below. If installation is blocked by your organisation, contact your IT team rather than changing security settings.

Find your way around VS Code

You should now see a window titled Visual Studio Code, with File, Edit, and View menus. A Welcome or getting-started tab is also normal. On Mac, these menus are in the menu bar at the very top of your screen.

This is the editor. The “Open Chat” shortcut and top “Sign In” button are not the Claude or Codex setup instructions. We will open your chosen assistant explicitly in Step 3.

You're done with this step when: this editor window is open. Leave it open and continue to Step 2.

Step 2 — Choose the assistant you will set up (1 minute)

You do not need to know how to open or sign in to an assistant yet. Step 3 shows you.

• If you are using your approved Claude account, follow Route A: Claude Code below.
• If you are using your approved ChatGPT/Codex account, follow Route B: Codex below.
• If you are using Google Antigravity, follow Route C: Antigravity IDE below.

Choose one route only: A, B, or C. Use your existing approved account; do not create a separately billed API account just to get through setup.

Next: follow your chosen route in Step 3. The sign-in happens there, not here.

Step 3 — Install your assistant, open it, and get your first reply (10 minutes)

An extension adds a tool to VS Code. Installing the extension does not necessarily open its chat. We will do those as separate actions.

3.1 — Choose your assistant

Click your assistant's name below to expand its setup instructions. Leave the other sections closed. At the bottom of your section, click Continue to setup handover.

Claude/Codex and VS Code screenshots show Windows; Antigravity screenshots are Google's examples. The extension names are the same on Mac; use the Mac shortcuts where given. Colours and button positions can change with updates. Match the names and publisher, not just the colour or icon.

Hello! Please reply to confirm this chat is working. Do not run commands or change files.

3.2 — Setup handover (everyone)

All three routes rejoin here. Use the assistant you just opened—Claude Code, Codex, or Antigravity.

You have now received your first reply. Stay in that same chat. Copy the whole message below, click the chat's message box, paste it, and click the send arrow:

Read https://raw.githubusercontent.com/BigChrisCooke/style-first-ai-workshop/master/WORKSHOP-SETUP-AGENT.md in full. Follow it as the controlling instructions for the rest of my workshop setup. Do not install or change anything yet. Tell me when you have read it.

Wait for the assistant to confirm that it has read the handover. The handover tells it which commands are valid, how to separate commands from expected output, and what it must not change during setup. If it cannot open the link, open that URL in your browser, copy the file's text into the same chat, and ask it to read it before continuing.

Then send:

I am on Step 4 of the workshop setup guide. Help me with one step at a time, following the setup handover. Explain each proposed change before asking my permission. Do not skip ahead, run forced dependency upgrades, or claim that a check passed without actually checking it.

You're done with this step when: your chosen assistant has replied to your first message and read the setup handover. File access and the working website will be tested after you open the actual workshop project in Steps 10–11; a chatbot saying it can do something is not that test.

Claude/Codex troubleshooting — only if a chat does not open

Open View → Extensions and search for your chosen extension ID again. Install means it is not installed yet; Enable means it is installed but disabled. Install or enable it, then retry the opening command from A3 or B3.

If the command is still missing, open View → Command Palette…, type Developer: Reload Window, and click that result.

After the editor reloads, retry A3 or B3. If that does not work, send Big Chris the step number and a screenshot. At this point you should not have to use an AI or PowerShell to repair the AI setup.

Switching assistants is not the same as switching models

To move from Claude Code to Codex, open Codex: Open Codex Sidebar. To go back, open Claude Code: Open in New Tab. These are separate chats and do not automatically share your previous conversation. Give a newly chosen assistant the setup handover in Step 3.2 before asking it to continue.

A model selector changes the model within an assistant. Choosing a Claude model in a different product does not open the Claude Code extension. You can leave the model on its default for the first-message test.

Your AI assistant can now help with the rest of setup

From here on, ask your AI to run the terminal commands and check their results. You handle installer windows, account sign-ins, permission prompts, and opening the preview. You do not need to open a terminal or type commands for the normal workshop setup.

For example:

“I'm on Step 4. Please check whether Node.js is installed and tell me the version. Run the check yourself.”

If the AI cannot run commands, ask it to explain the permission or workspace it needs. If it needs an open folder before Step 10, use an empty workshop-setup folder in Documents. Do not disable security controls to make it work. If execution is still unavailable, ask Big Chris for help; manual commands are a fallback, not the default route.

If your assistant accepts images, you can also attach a screenshot. Include a short question such as “What does this error mean?”

Always read permission prompts before approving them. If a suggested command asks to delete files, change security settings, or requests administrator access you were not expecting, stop and ask Big Chris.

Step 4 — Install Node.js (5 minutes)

Node.js lets your computer run the website locally so you can preview it while building.

Recommended: use the official installer

1. Go to https://nodejs.org/en/download.
2. Make sure LTS and your operating system are selected. The workshop project requires Node 22.12 or newer; the current Node 24 LTS is recommended.
3. Do not use the Docker instructions shown in the large command box. Scroll down to the prebuilt download buttons instead:
   • Windows: select Windows Installer (.msi).
   • Mac: select macOS Installer (.pkg).

*The large command box at the top is for Docker and is not what you want. Scroll past it to Or get a prebuilt Node.js and click Windows Installer (.msi) or, with macOS selected, macOS Installer (.pkg).*

4. Open the downloaded installer and accept the defaults.
5. Save open work, fully quit every VS Code window (or Antigravity window), and reopen the editor so it can detect Node.js.
6. Reopen your chosen assistant using its section in Step 3. If the chat has restarted, give it the Step 3.2 setup handover again. Then paste this into AI chat, not a terminal:

I have installed Node.js and restarted my editor. Please run the version check yourself and tell me whether it meets the workshop requirement of Node 22.12 or newer. Do not reinstall or upgrade anything without explaining why.

Approve the version check if prompted, then wait for the actual result.

You're done with this step when: your AI has run the check and reported a supported Node version.

Step 5 — Install Git (5 minutes)

Git tracks every change made to your project. Mac users may already have it installed.

Paste into AI chat:

Please check whether Git is installed by running the version command yourself. If it is missing, guide me through the official installation for my operating system, then verify it again. Follow the workshop setup handover.

If Git is already installed, no installation is needed. Otherwise:

• Mac: if macOS offers to install developer tools after the AI's check, approve the official prompt and wait for it to finish.
• Windows: go to https://git-scm.com/downloads, select the Windows tab, then Click here to download. Open the installer and accept the defaults.

Use the top Click here to download link. You do not need the winget, Chocolatey, or portable options further down.

After installation, save open work, fully quit every editor window, and reopen your editor and assistant using Step 3. Give it the Step 3.2 handover again if this is a new chat. Ask it to recheck Git. Restarting the whole editor matters: a new terminal inside an old editor window can still use the old environment.

You're done with this step when: your AI has run the check and reported the installed Git version.

Step 6 — Create a GitHub account (5 minutes)

GitHub is where your project's code will live online. A free account is enough for this workshop.

1. Go to https://github.com/signup.
2. Sign up with an email address you check regularly.
3. Choose a simple, professional username. It will become part of your project URLs.
4. Verify your email address.

You're done with this step when: you can sign in to GitHub and see your username.

Step 7 — Tell Git who you are (2 minutes)

Git needs a name and email address to label the changes you save. This is a one-time setup on each machine.

Paste into AI chat:

Please check my Git author name and email. If either is missing, ask me what to use, explain that a global Git setting affects all repositories on this computer, and get my approval before setting it. Do not overwrite existing values without asking. Read the settings back to verify them.

Use an email you are comfortable associating with public commits, such as your GitHub-provided no-reply address. Your assistant can help you find it in GitHub's email settings. Do not share your password or access token.

You're done with this step when: the AI has verified the name and email you want attached to your commits.

Step 8 — Create a Vercel account (5 minutes)

Vercel is where your finished website will be hosted. Sign up using your GitHub account so the two services are already linked.

1. Go to https://vercel.com/signup.
2. Select Continue with GitHub.

Choose Continue with GitHub, not Google, ChatGPT, Apple, or email, so Vercel can deploy from your repository later.

3. Review and approve the requested GitHub access.
4. Choose a simple username or Hobby team name.
5. Skip any “import a project” prompts for now.

You're done with this step when: you can sign in to Vercel and see your dashboard.

Step 9 — Create your project from the workshop template (5 minutes)

Instead of setting up a website from scratch, you'll begin with a ready-made starter project. It includes the website tools, a brand.md brief, and a WORKSHOP.md project-instructions file that any suitable AI assistant can read when asked.

1. Go to https://github.com/BigChrisCooke/style-first-ai-workshop.
2. Select the green Use this template button.
3. Select Create a new repository.
4. Give it a name, such as my-first-site.
5. Select Public so Vercel can deploy it during the workshop.
6. Select Create repository.
7. GitHub will create your copy. Note its URL, which will look like github.com/your-username/my-first-site.

You're done with this step when: you can see your new repository at its own GitHub URL.

Step 10 — Clone the project and open it in VS Code (5 minutes)

“Cloning” means downloading your GitHub repository to your computer so you can work on it locally.

Recommended: clone from VS Code

1. Copy the URL of the repository you created in Step 9.
2. Open VS Code.
3. Press Ctrl + Shift + P on Windows or Cmd + Shift + P on Mac.
4. Type Git: Clone and select it.

5. Paste your repository URL and press Enter.

Paste your own repository URL from Step 9 in place of your-username/my-first-site, then press Enter to choose Clone from URL.

6. Choose a sensible location, such as a projects folder inside Documents.
7. When cloning finishes, select Open.
8. VS Code may open the folder in Restricted Mode, with a banner saying “Trust this folder to enable all features”. Click Manage in that banner, then Trust. Confirm only after checking that the folder is your copy of BigChrisCooke/style-first-ai-workshop. In Restricted Mode your AI assistant will not be able to run.

Click the blue Trust button. Until you do, the extensions (including Claude Code and Codex) stay disabled for this folder.

Optional: ask your AI assistant

If your assistant can clone repositories from inside VS Code, you may ask:

Please clone my GitHub repository at https://github.com/your-username/my-first-site into a projects folder inside my Documents folder, then help me open it in VS Code. Explain the command before running it.

You should now see WORKSHOP.md, brand.md, and package.json in the file explorer on the left.

The Explorer on the left lists your project. If you cannot see it, click the top icon in the left-hand bar or press Ctrl + Shift + E (Cmd + Shift + E on Mac).

You're done with this step when: VS Code shows your cloned project folder and those files are visible.

Before Step 11 — hand the project to your AI now

This is when to give your AI the workshop instructions: immediately after opening your own project, before any dependency installs or project tests.

1. Keep your cloned project open. Open your chosen assistant's chat as shown in Step 3; opening a project may have started a new chat.
2. Copy the whole message below, click the AI chat message box (not the terminal), paste it, and send:

Read WORKSHOP.md and WORKSHOP-SETUP-AGENT.md in this project in full. Prove you can access them by telling me one specific workshop rule and the project folder you are working in. Then perform the Step 11 setup checks yourself: verify Node and Git, install the locked project dependencies and matching Playwright browser, run the workshop scope tests and build, and start the local preview. Explain proposed commands and use the editor's normal permission prompts. Do not repeat completed installations, change security settings, or upgrade dependencies. Give me the actual preview link and wait for me to confirm that the starter page opens. Do not start designing or building my landing page yet.

Claude Code opened inside the project: the project files on the left, the chat on the right, and the message box at the bottom. Codex and Antigravity look different but the idea is the same: the chat must be open with your project folder.

3. Wait for the AI to identify your project and a rule from the files, such as building only one homepage. If it cannot read them, check that WORKSHOP.md is visible in the editor's file explorer and that you opened the project itself, not its parent folder. Do not proceed on a claim that it can read files without this evidence.

View WORKSHOP.md on GitHub if you want to inspect the instructions. You do not need to paste that URL or the whole document: your project already contains the Markdown files.

Step 11 — Let your AI install and test the project (10–15 minutes)

The handover above starts this step. Your AI runs the commands; you do not need to open a terminal or type them. Keep the project and AI chat open while it works.

What the AI does

It checks the installed Node and Git versions, installs the project's locked dependencies, downloads the matching browser for screenshots, runs the one-page scope tests and website build, and starts the preview. The exact commands and safe Windows alternatives are in WORKSHOP-SETUP-AGENT.md, which it has just read.

Downloads can take several minutes. A successful check means the AI has read the real command output, not just told you that something should work.

What you do

1. Read permission prompts. Approve the expected project checks and downloads when you are happy with them. You do not need to enable unrestricted access.
2. Wait for the AI to give you the actual local preview link, then click it to open your browser.
3. You should see the starter message “Your one landing page starts here.” Tell the AI whether it loads. If it does not, send it the error or a screenshot and let it investigate.

This is the whole starter page: one line of text on a white background. That is correct. The style is the exercise. 4. Once checked, ask the AI to stop this project's preview server. It will start it again when you begin building.

If the AI only lists terminal commands, reply: “Please run these checks yourself using your terminal tools, following the setup handover. Ask me for any required permission.” If it cannot execute them, ask it to identify what is blocked; contact Big Chris if needed. Do not disable security settings to work around this.

If it reports high or critical vulnerabilities, stop and send Big Chris its findings. The template needs a maintainer update; the AI must not run audit-fix commands or dependency upgrades.

You're done with this step when: the AI reports that the version checks, dependency and browser installation, scope tests, and build passed; no high or critical audit findings remain; and you have opened the starter page yourself. It should name any unfinished check instead of calling you ready.

Step 12 — Pick one style reference and your page's purpose (5 minutes)

Write down:

1. One reference page URL whose visual style you like. Choose a page you can view without signing in.
2. What your landing page is about, in one sentence.
3. What visitors should do, such as enquire, book, view your work, or follow an approved external link.

Example: “I like the visual style of this product homepage. My page is for my pottery classes, and I want visitors to email me to book.”

The reference can be about something completely different. Your assistant will inspect that one page, suggest the typography, colours, spacing, and layout, and draft a headline and sections for your subject. You do not need to design a brand from scratch.

Scope stays at one homepage, served at /. Navigation uses sections on that page. Do not ask the AI to crawl the reference site or reproduce its multiple pages.

Once setup checks pass, send your assistant:

Read WORKSHOP.md and brand.md. My style reference page is [URL]. My landing page is about [topic], and I want visitors to [action]. Inspect only that reference page. Summarise its visual style and propose a brief for one homepage at /. Do not create extra pages or start building until I approve the brief.

You're done with this step when: your reference URL, topic, and desired visitor action are recorded. During the workshop you will approve the brief, build the hero first, and then finish the same page.

Quick troubleshooting

First port of call: paste the exact error into your AI coding assistant and say which step you are following. Read any proposed command before approving it.

“Command not found” appears for node --version or git --version

• Save work, fully quit the editor, and reopen it and your assistant. An editor opened before installation may not see the new tools.
• Ask the AI to rerun the version check. If it still fails, give it the exact error and ask for the next safe step; do not change system settings blindly.

PowerShell says run is not recognised

• The command may have included an instruction label by mistake. This error alone does not prove whether Node is installed.
• Send the error to your AI and ask it to reread WORKSHOP-SETUP-AGENT.md, then run the exact version check itself. It must not execute labels, prompts, or expected output as commands.

The Node download page is showing Docker commands

• You do not need Docker for this workshop.
• Confirm that LTS and your operating system are selected, then scroll down and choose the prebuilt Windows Installer (.msi) or macOS Installer (.pkg).

My AI assistant is unavailable or says I've reached a usage limit

• Check your provider's account status and usage-limit information.
• Avoid pasting entire large files when only one error or section is relevant.
• Ask Big Chris about the workshop fallback; do not purchase an upgrade under time pressure.

My AI assistant cannot access the project

• Confirm the cloned project folder is open in VS Code.
• Check that the assistant has permission to read the workspace.
• Follow the provider's official instructions for connecting it to VS Code.

My assistant cannot see WORKSHOP.md

• Ask it explicitly to read WORKSHOP.md from the project root.
• Confirm the file is visible in VS Code's file explorer.
• If the file is missing, ask the AI to check which repository is open, or ask Big Chris for help. Do not overwrite your work or clone another copy blindly.

I can't find the workshop template

• Go to https://github.com/BigChrisCooke/style-first-ai-workshop.
• Sign in to GitHub if the Use this template button is missing.

Git asks me for credentials when I push

• Do not enter your normal GitHub password into an unfamiliar prompt.
• Follow GitHub's current official authentication instructions or ask Big Chris for help.

A terminal command looks frozen

• See “Normal developer-tool behaviour” below.

Normal developer-tool behaviour

Some terminal commands keep running — that can be correct

When your AI starts the local preview, the server needs to keep running while you view the page. Some versions keep its terminal busy; others run in the background. This is not necessarily a freeze.

Ask the AI whether it is waiting for you to check the preview link. When you are finished, ask it to stop only this project's preview server; you do not need to type a stop command.

AI assistants ask for permission

An assistant may ask before reading files, editing files, or running a terminal command. This is a safety feature.

Read the proposed action before approving it. Stop and ask for help if it wants to delete files, change security settings, expose credentials, or use administrator access unexpectedly.

AI services can have usage limits

Limits vary by provider and account plan. If your assistant becomes unavailable during the workshop, save your work and tell Big Chris. A workshop fallback is better than purchasing an unplanned upgrade.

What you'll have at the end of the workshop

By the end, you'll have:

• One live homepage/landing page on the internet, such as yourname.vercel.app.
• A GitHub repository containing your code.
• Confidence building and iterating with an AI assistant.
• An understanding of how project instructions guide an AI assistant.
• A reusable website-building toolchain.

Glossary

Pre-workshop checklist

• My chosen editor (VS Code or Antigravity) opens cleanly.
• I can send a message to my chosen AI assistant and receive a reply.
• My assistant can read my project files and run commands with the required approval.
• My AI checked Node and reported version 22.12 or newer.
• My AI checked Git and reported its version.
• I can sign in to GitHub.
• Git has my name and email.
• I can sign in to Vercel through GitHub.
• I created a repository from https://github.com/BigChrisCooke/style-first-ai-workshop.
• I cloned the repository and can see WORKSHOP.md, brand.md, and package.json in VS Code.
• My AI installed the locked dependencies and reported no unresolved high or critical vulnerabilities.
• My AI installed the matching Playwright browser and passed the scope tests and build.
• I opened the AI's preview link and saw the starter page.
• My AI assistant read WORKSHOP.md and reported one specific workshop rule.
• I chose one reference page URL and wrote down my page's topic and desired visitor action.

If every box is ticked, you're ready. See you in Session 1!

Reference links — use only when a numbered step sends you here

Ready to start? Give your AI the workshop handover

Open WORKSHOP.md — the instructions for your AI assistant

Use this immediately after Step 10, before Step 11. The project handover above is the main starting point. If you already sent it, continue with your existing chat; you do not need to restart setup. With your own workshop project open, this short reminder also works:

Read WORKSHOP.md and WORKSHOP-SETUP-AGENT.md in this project. Run the Step 11 setup checks yourself using the editor's normal permission prompts. Do not repeat completed installations. Give me the preview link and wait for me to confirm it opens. Then help me prepare a brief for one landing page using one reference page's visual style, not its multi-page architecture. Don't start building until I approve the brief.

The handover is Markdown the AI can read directly. The repository also includes AGENTS.md, CLAUDE.md, and GEMINI.md entry points that direct different assistants to the same shared instructions.

View all workshop files on GitHub