How the pieces fit
Four tools, each with one job
You do not need to write code. You need to know what each tool is for, so you know where to look when something needs changing.
NOAN
Your facts: who you are, what you sell, what it costs, how you talk about it. Your site reads them live, so the page and the truth cannot drift apart.
Claude
You describe what you want in plain words. Claude writes the design system, the code and the pages, following your brand and your facts.
GitHub
Where the site's code lives. Every version is kept, and every change arrives as a proposal, called a pull request, that you read before it goes live.
Netlify
Watches GitHub. When you accept a change it builds and publishes the site, and every proposal gets its own preview link first.
And the part most sites cannot do: change a fact in NOAN, such as a price, and the live site shows the new one without anyone touching the code.
Before you start
Four accounts, ten minutes
- 01Claude, with Claude Code. Use it in the Claude desktop app's Code tab, or in a terminal. This is where you will do almost everything.
- 02A GitHub account. The free plan is enough.
- 03A Netlify account. Sign up with your GitHub account so the two are already linked. The free plan is enough to start.
- 04A NOAN workspace with your facts in it: your positioning, products, pricing and brand. The more of your company is in NOAN, the less you will type into Claude.
Step 1 · Explore
Explore your look before you commit
Your brand might live in NOAN, on your current website, in a PDF of guidelines, or nowhere yet because you want something new. Start with an exploration: give Claude everything you have, and it shows you a few directions to choose from before anything is built.
Gather your references
- 01Make a folder for your site on your computer and open it in Claude Code. Inside it, make a folder called references.
- 02Put in anything that shows your brand or the look you want: logo files, brand guidelines, fonts, photos, and screenshots of websites you admire. You can also drag a file straight into the Claude chat.
- 03If you already have a website, have its address ready. Claude can read it and pick up its colors, type and tone.
- 04Connect NOAN to Claude Code with the command below, then type /mcp in a session to sign in. If your brand is in NOAN, the exploration reads it; either way, the page prompts later read your facts through this connection.
claude mcp add --transport http noan https://mcp.getnoan.com/mcpnpx skills add getnoan/skillsNow ask for the exploration. Paste your website address into the prompt where it says so, or delete that line if you do not have one.
Run a design exploration for our new website. Do not build the site yet.
First, gather what we already have and tell me what you found:
- Everything in the references folder in this project: logos, brand guidelines, fonts, photos, and screenshots of websites we like.
- Our current website, if we have one: https://www.example.com (replace with our address, or delete this line). Look at its colors, type, imagery and tone of voice.
- Our brand, positioning and key messages in NOAN, if they are there.
Then propose three distinct directions:
1. Close to what we have today, cleaned up and made consistent.
2. An evolution: still recognizably us, but bolder and more modern.
3. A new look, taking its cue from the references we like.
For each direction, make one simple page in a folder called explorations that opens in my browser, showing the palette, the fonts, a homepage hero, a card, buttons and a form field, with three lines on the thinking behind it. Open all three for me side by side, then ask which one to take forward, or what to mix from each.The exploration is sketches, not the website: three simple pages you open in your browser and compare. It costs one prompt, and it means you choose the look with your eyes before a single real page depends on it.
Step 2 · Design system
Turn your choice into a design system
A design system is the rulebook for how your site looks: colors, fonts, spacing and the building blocks every page is made from. Write it from the direction you chose, and every page after it looks like it belongs to the same company.
We are going with direction 2 from the exploration (change the number, and add anything you want mixed in from the others). Turn it into our design system as one file called DESIGN.md, plus the matching design tokens in code.
Include:
- Principles: three to five lines on how the site should feel.
- Color: a full palette as named tokens (background, surface, text, muted text, primary, accent, border, success, warning, error) with light and dark values, and contrast that passes WCAG AA.
- Type: display, heading and body fonts, a type scale, line heights and letter spacing. Use free fonts unless we have licensed ones in the references folder.
- Spacing, corner radius, shadows, and a layout grid with breakpoints for phone, tablet and desktop.
- Motion: durations and easing, and what changes when a visitor prefers reduced motion.
- Components, each with its states (default, hover, focus, disabled) and when to use it: header with a mobile menu, footer, buttons (primary, secondary, quiet), links, hero, section, card, feature grid, pricing card, testimonial, FAQ, form fields and a contact form, badge, callout, code block, image with caption, and a closing call-to-action band.
- Voice: how headlines and body copy should read, from our references and, if they are there, our key messages in NOAN.
Show me every component on one preview page before you build anything else. Do not invent facts about the company: if you need something you cannot find, ask me.The design system lives as a file next to the code, so every page Claude builds later follows the same rules, and a change to the rules changes every page. Your references stay in the project, so Claude can go back to them whenever it needs to.
Step 3 · GitHub
Give the site a home on GitHub
GitHub keeps your site's code and every version of it. Claude does the setup; you sign in once when it asks. The prompt uses TanStack Start and Tailwind, the tools getnoan.com is built with, and Claude will explain them if you ask.
Set this project up to live on GitHub.
1. Check that git and the GitHub command line tool are installed, and install anything missing. Then run "gh auth login" and walk me through signing in, one step at a time.
2. Create a new private repository on my GitHub account called my-company-site, from this folder.
3. Create the website project here with TanStack Start and Tailwind CSS, keeping DESIGN.md and the references and explorations folders. Turn DESIGN.md into the Tailwind theme and build each component from it as a reusable piece, with the preview page kept at /design.
4. Add a README that explains, in plain words, how to run the site on this computer.
5. Commit and push. From now on, make every change on its own branch and open a pull request for me to review. Never push straight to main.From here on nothing goes live by accident. Claude proposes each change as a pull request, a page on GitHub that shows exactly what changed, and you decide whether to accept it. If anything ever goes wrong, every earlier version is one click away.
Step 4 · NOAN
Connect the site to your facts
This is the step that makes the site work like ours. Instead of typing your prices and product lines into the code, the site asks NOAN for them every time it loads.
Our website should read its facts live from NOAN instead of having them typed into the code.
- Read the NOAN API docs at https://api.getnoan.com/docs/ and the skill at https://getnoan.com/skill.md.
- Create one small server-only module that calls https://api.getnoan.com/v1 using the key in the NOAN_API_KEY environment variable. The key must never reach the browser or the repository.
- Add a .env.example that names NOAN_API_KEY with no value, and make sure .env is listed in .gitignore.
- Keep what you read for a few minutes so the site stays fast, and if NOAN cannot be reached, show the last good version rather than an error.
- Open a pull request when it works.The API key is the site's password to your NOAN workspace, so it is kept in an environment variable: a setting stored on the computer and later in Netlify, never in the code on GitHub. That way anyone can read your code without being able to read your workspace.
Step 5 · Pages
Build your pages, the NOAN way
Now the real pages, built the way ours are: one component library, every claim read from a fact, nothing invented. The first prompt writes those rules into the project, so every page after it follows them.
Build our homepage from the design system in DESIGN.md.
These are the rules for every page on this site. Save them in a file called CLAUDE.md in the repository so you follow them on every page from now on:
- Every claim comes from our facts in NOAN. Nothing is made up, and nothing NOAN already holds is typed into the code.
- Pages are built only from the components in the design system, never one-off styles.
- Wherever a price, a feature list or a policy appears, render it from the fact when the page loads, not as typed text, so when the fact changes the page changes.
- If a fact you need is missing from NOAN, leave that part out and tell me, rather than guessing.
Then build the page:
- Read our positioning, value proposition, product features and key messages from NOAN first.
- Sections: a hero with one headline and one line under it, what we do, how it works in three steps, who it is for, proof, and a closing call to action.
- Mobile first, fast, accessible, with a real mobile menu.
Open a pull request when it is ready and give me the preview link.Add a pricing page and an about page, using the same components.
- Pricing: render every plan, price and feature from our pricing facts in NOAN, with a small note that the prices are live. If a price is missing from NOAN, show nothing rather than guessing.
- About: our mission, our story and our team, read from NOAN.
- Link both from the header and the footer, add them to the sitemap, and give each its own page title and description for search.
One pull request, with the preview link.Pages are made from the components in step 1 and filled from the facts in step 3. That is why they stay consistent and stay true: the look comes from one place, and the words come from one place.
Step 6 · Netlify
Put it live with Netlify
Netlify turns what is on GitHub into a website anyone can visit, and publishes again every time you accept a change.
Get this project ready for Netlify.
- Add a netlify.toml with the build command and the folder Netlify should publish, and pin the Node version.
- Run the same build command here that Netlify will run, and fix anything that fails.
- Tell me, in plain words, the exact settings to check when I import the repository into Netlify, and which environment variables I must add there.- 01In Netlify, add a new project and import it from GitHub. Pick the repository Claude created.
- 02Check the build settings match what Claude told you. With a netlify.toml in the repository they fill themselves in.
- 03In the project's environment variables, add NOAN_API_KEY with your key. This is the same key as step 3, now given to Netlify instead of your computer.
- 04Deploy. In about a minute you have a live address, and you can connect your own domain in the project's domain settings.
Netlify now watches your repository. Every pull request gets its own preview address, so you see a change on a real site before anyone else does, and accepting it publishes it.
Step 7 · Every day
Change it the way we change ours
Once it is running, there are only two kinds of change, and you already know where each one happens.
The words and numbers
Change the fact in NOAN. A new price, a renamed plan, a sharper line: verify it and the live site shows it. No code, no Claude, no deploy.
The pages and design
Ask Claude. It proposes the change on GitHub, Netlify gives you a preview, and you accept it or ask for another pass. This is how every change to getnoan.com is made.
Start with your facts
Everything in this guide reads from NOAN. Put your company in once, and your site, your agents and your team all work from the same truth.