A system that builds an on-brand website whose pages stay consistent with each other

How the system fits together

Brand information and permitted examples → DESIGN.md → import from CLAUDE.md → a single design skill → components that fit the project → build two pages → check in the browser and at 390 pixels wide.

• 
  Claude Code required

  Writes and reads DESIGN.md and builds the pages

  Tool guide

• 
  DESIGN.md format required

  Keeps the brand rules in a single file the agent reads

  Tool guide

• 
  Frontend Design plugin (Anthropic) required

  The single main design skill: guides aesthetic direction, font and color choices

  Alternative: If another design skill is already installed in your project and works well, keep that one as the single main skill; don't require both

  Tool guide

• 
  shadcn/ui component command optional

  Adds ready-made components such as buttons and forms to your project

  Alternative: Only if you really need a component your project doesn't have; if the existing components are enough, don't install it at all

  In design resources

• 
  Playwright CLI required

  Opens the page in a browser and takes a screenshot at phone width

  Tool guide

• 
  Awesome DESIGN.md optional

  Read for inspiration from other sites' design language; not copied into your brand

  Alternative: Not needed if you already have your own brand guide or logo/color files

  In design resources

• 
  Refero Styles optional

  Live design research on a paid plan

  Alternative: If the reference list you prepared isn't enough and you want to buy a paid plan

  In design resources

Before you start

Step-by-step setup

The steps you check stay only in this browser; they do not confirm that the setup works. You finished 0/9 steps.

1. Step 1 · In the terminal

   Prepare the project you'll work in

   I finished this step

   What for: Have a runnable project folder where the pages will be written.

   1. If you already have a React project, open the terminal in that folder and skip this step's command; don't upgrade anything. The component step (shadcn) assumes a TypeScript project; if your project is JavaScript, skip that step.
   2. If you're starting fresh, check your Node.js version, then create the React + TypeScript template with the command below. Because --no-immediate is passed, you won't get the 'install dependencies and start' prompt; installing and starting are done by hand in the next item.
   3. If the terminal is interactive, you may get the 'Which linter to use?' (Oxlint / ESLint) prompt. If you're not sure, leave the first option, Oxlint, and press Enter. If you don't want any prompts, you can also add --no-interactive to the command.
   4. Go into the project folder, install the packages (npm install) and start the development server with npm run dev. The address the server prints should open in the browser.
   Windows · macOS · LinuxFolder: Any folder

   › node --versionCopy

   Windows · macOS · LinuxFolder: The parent folder where you want to put the project

   › npm create vite@9.2.1 marka-sitesi -- --template react-ts --no-immediateCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   Windows · macOS · LinuxFolder: marka-sitesi

   › npm run devCopy

   How you know it worked

   • The terminal prints a local address, and that address opens the template page in the browser.
   If you get stuck: problems specific to this step

   • The command complains about the Node.js version
     Vite requires Node.js 20.19 or later, or 22.12 or later; upgrade your version and run the command again.
   • The project opened but the browser shows a blank page
     Make sure the development server is still running in the terminal and that you entered the address the terminal printed into the browser.
   Based on: Vite docs: getting started and Node.js requirement, npm registry: create-vite (current version 9.2.1), vitejs/vite: create-vite source code (options: --template, --immediate, --interactive), shadcn/ui docs: Vite installationGet help with this step →
2. Step 2 · In a code editor

   Gather your brand information and permitted examples

   I finished this step

   What for: Have the raw material for DESIGN.md ready, with what it should and shouldn't look like written down.

   !You check this step yourself; the system should not move past it without your approval.

   1. In a notes file, write the brand name, who it speaks to, its tone in 2-3 adjectives, the logo and color codes, the fonts you use and the purpose of the site. If you have a brand guide, add it too.
   2. As examples, use only screenshots of your own sites, images you have permission to use, or your own sentences describing the design language you like.
   3. Optional: read a file from the Awesome DESIGN.md repository for inspiration. The repository's README has no link to terms of use; the terms are at getdesign.md/terms, so read that first. The files are analyses extracted from other companies' sites: don't copy their logos, brand names or images into your product, and don't make a product that could be confused with another brand (the Terms prohibit this).
   4. Don't download and copy a competitor site's code or images. This guide doesn't cover that route.

   How you know it worked

   • You have a single notes file with the brand name, tone, colors, fonts, purpose and the list of permitted examples.
   If you get stuck: problems specific to this step

   • The brand has no written guide
     Pick the color and font yourself from your existing logo and site, and write the reason in one sentence; that's what the prose part of DESIGN.md is for.
   Based on: VoltAgent/awesome-design-md: README and license note, getdesign.md Terms (use of the DESIGN.md files in the directory)Get help with this step →
3. Step 3 · In a coding agent

   Write and check the DESIGN.md file

   I finished this step

   What for: Keep your design rules in a single file the agent reads every time.

   !You check this step yourself; the system should not move past it without your approval.

   1. Start Claude Code in the project folder, show it your notes file and ask: create DESIGN.md in the root folder; put the color, font, corner radius and spacing values at the top; below that, include the spec's English headings in this order: Overview, Colors, Typography, Layout, Components, Do's and Don'ts. Keep the headings in English; the descriptions can be in your site's language.
   2. According to the spec, all sections are optional, but the ones you write must be in this order. The section at the top of the file (front matter) holds the color, font and spacing values in machine-readable form; the prose part explains the reasons for those values.
   3. Read the file and have the parts that don't fit your brand fixed. Then check its format with the command below. The command treats references to tokens that don't exist (e.g. a link to a color that doesn't exist) as errors; if you define components, it also reports the contrast of their text/background color pairs as warnings. The short example below has no components, so contrast isn't checked.
   Windows · macOS · LinuxFolder: marka-sitesi (or your own project folder)

   › npx -p @google/design.md@0.4.0 designmd lint DESIGN.mdCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   DESIGN.md (short format example) · markdownCopy

   ---
   name: Heritage
   colors:
     primary: "#1A1C1E"
     secondary: "#6C7278"
     tertiary: "#B8422E"
     neutral: "#F7F5F2"
   typography:
     h1:
       fontFamily: Public Sans
       fontSize: 3rem
     body-md:
       fontFamily: Public Sans
       fontSize: 1rem
   rounded:
     sm: 4px
     md: 8px
   spacing:
     sm: 8px
     md: 16px
   ---
   
   ## Overview
   
   Architectural Minimalism meets Journalistic Gravitas.
   
   ## Colors
   
   The palette is rooted in high-contrast neutrals and a single accent color.
   
   - **Primary (#1A1C1E):** Deep ink for headlines and core text.
   - **Tertiary (#B8422E):** the sole driver for interaction.

   A format example taken from the official repository's short example. Change the colors, name and fonts to fit your brand.

   How you know it worked

   • DESIGN.md is in the root folder.
   • The lint command finishes without reporting an error; warnings may appear, and that's normal.
   If you get stuck: problems specific to this step

   • The lint command reports an error and exits with code 1
     The path and message fields in the output tell you which value is broken; it's usually a link to a color that doesn't exist. Have it fixed and run the command again.
   • The spec is at version 'alpha', and field names may have changed
     Keep the version in the command pinned; read the spec in the repository before moving to a new version.
   • In Windows PowerShell the lint command prints nothing, or DESIGN.md opens in a Markdown editor
     The README says the .md extension in the package's bin name clashes with the Windows file association and recommends the dotless designmd alias. That's why the command is written as npx -p ... designmd lint; don't use the direct npx @google/design.md ... form.
   Based on: google-labs-code/design.md: repository and README (format, lint command, license), DESIGN.md spec (docs/spec.md, version: alpha), npm registry: @google/design.md (current version 0.4.0)Get help with this step →
4. Step 4 · In a code editor

   Introduce DESIGN.md to Claude Code

   I finished this step

   What for: Have the agent read the design rules automatically in every session.

   1. If there is no CLAUDE.md file in the project root, create one; according to the documentation, project instructions live in CLAUDE.md or .claude/CLAUDE.md at the root.
   2. Add the @DESIGN.md line to the file as in the example below. According to the documentation, a file referenced with @ is loaded into context at the start of the session, so keep DESIGN.md short and essential.
   3. Close and restart Claude Code and ask it: 'which file holds the design rules? Summarize them for me.'
   CLAUDE.md · markdownCopy

   # Project instructions
   
   Follow this file for design rules:
   @DESIGN.md
   
   On new pages, don't make up color, font or spacing values outside DESIGN.md.

   The @path/file syntax comes from the import section of the documentation; the second sentence is DijiKoçum's recommendation.

   How you know it worked

   • Claude Code summarizes the design rules from the content of DESIGN.md.
   If you get stuck: problems specific to this step

   • Claude Code acts as if it doesn't know about DESIGN.md
     Make sure the line isn't written inside backticks; an @path inside a code block or backticks isn't imported. Close the session and open it again.
   Based on: Claude Code docs: CLAUDE.md and importing files with @
5. Step 5 · In a coding agent

   Install a single main design skill

   I finished this step

   What for: Keep the agent from falling into generic, template looks on aesthetic decisions, without loading lots of skills that duplicate each other's work.

   1. The single skill this guide recommends is Anthropic's Frontend Design plugin. Type the command below inside a Claude Code session; the install screen shows what the plugin adds, so read it and choose the scope (just this project or all your projects).
   2. If another design skill is already installed in your project and does the job, keep it; don't add a second design skill. Loading skills that do the same job together can mix up their instructions.
   3. Note: this plugin can't be installed pinned to a version. Its marketplace entry has no version or commit pin, and according to the documentation, plugins in the official marketplace update automatically by default; the plugin's behavior may change over time. That's why you keep your design rules independent of the plugin, in your own DESIGN.md file.
   4. Once the plugin is installed, type / in the input box and look for the name frontend-design in the list.
   Windows · macOS · LinuxFolder: Claude Code session (open in the project folder)

   › /plugin install frontend-design@claude-plugins-officialCopy

   How you know it worked

   • The install summary says 'Plugin is now active' or asks for a reload.
   • When you type /, the plugin's skill appears in the list.
   If you get stuck: problems specific to this step

   • After installing, the skill doesn't appear in the list
     The last sentence of the install summary tells you whether the plugin is active right away; if needed, run the /reload-plugins command.
   • The plugin can't find the marketplace
     According to the documentation, the official marketplace is added automatically in the first interactive session; if you're installing from the terminal, you may first need the command 'claude plugin marketplace add anthropics/claude-plugins-official'.
   • The plugin updated and the agent behaves differently
     According to the documentation, auto-update is on by default in the official marketplace. Keep your rules in DESIGN.md; if needed, turn the plugin off from the /plugin screen.
   Based on: Claude Code docs: installing plugins, anthropics/claude-plugins-official: marketplace.json (frontend-design entry), anthropics/claude-code: frontend-design plugin READMEGet help with this step →
6. Step 6 · In the terminal

   If needed, add ready-made components that fit your project

   I finished this step

   What for: Instead of having a part your project lacks, like a button or form, written from scratch, add it as a ready-made component.

   !You check this step yourself; the system should not move past it without your approval.

   1. First have the agent list the existing components in the project and check whether the part you need already exists. If it does, skip this step. Also skip it if your project isn't TypeScript: shadcn's Vite documentation assumes the React + TypeScript template.
   2. The order in the documentation for an existing project: install Tailwind CSS, replace the contents of src/index.css, add the @ path alias to the tsconfig files, update vite.config.ts, then run the shadcn init and add commands. The documentation also lists installing @types/node; in a new project the create-vite template already includes it, so skip that command.
   3. Important: the template's root tsconfig.json has no compilerOptions section (only files and references); you have to add it yourself. The documentation also includes a baseUrl line, but TypeScript 6.0 deprecated baseUrl and the template installs TypeScript ~6.0.2, so the examples below only have paths.
   4. Do the commands and file edits below in order; don't delete existing settings in your own files, only add what's missing.
   5. Alternative: the documentation also gives npx shadcn@latest init -t vite for starting from scratch (it creates a new Vite project); this guide follows the order above as the main path.
   6. init asks questions; if you don't understand what you're choosing, stop and ask for help.
   Windows · macOS · LinuxFolder: marka-sitesi (or your own project folder)

   › npm install tailwindcss@4.3.3 @tailwindcss/vite@4.3.3Copy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   Windows · macOS · LinuxFolder: marka-sitesi (or your own project folder)

   › npx shadcn@4.22.0 initCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   Windows · macOS · LinuxFolder: marka-sitesi (or your own project folder)

   › npx shadcn@4.22.0 add buttonCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   src/index.css · cssCopy

   @import "tailwindcss";

   According to the documentation, the file's entire content is replaced with this line; if you have existing styles, back them up first.

   tsconfig.json (root; add the compilerOptions section) · jsonCopy

   {
     "files": [],
     "references": [
       { "path": "./tsconfig.app.json" },
       { "path": "./tsconfig.node.json" }
     ],
     "compilerOptions": {
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }

   The template's root tsconfig.json has no compilerOptions; it only has files and references. The paths field is taken from the shadcn Vite documentation; the baseUrl line was left out because of TypeScript 6.0. If init gives a path alias error, adding "ignoreDeprecations": "6.0" together with baseUrl: "." is the temporary workaround in the TypeScript announcement.

   tsconfig.app.json (the part to add inside the existing compilerOptions) · jsonCopy

   "paths": {
     "@/*": ["./src/*"]
   }

   The documentation has you add the same field to tsconfig.app.json as well (the documentation's baseUrl line was removed because of TypeScript 6.0). This file already has compilerOptions; keep the existing settings.

   vite.config.ts · typescriptCopy

   import path from "path"
   import tailwindcss from "@tailwindcss/vite"
   import react from "@vitejs/plugin-react"
   import { defineConfig } from "vite"
   
   export default defineConfig({
     plugins: [react(), tailwindcss()],
     resolve: {
       alias: {
         "@": path.resolve(__dirname, "./src"),
       },
     },
   })

   This is the example from the documentation; if your template has other plugin settings, keep them.

   How you know it worked

   • src/index.css contains the Tailwind line, components.json is created, and the added component's file appears in the project.
   If you get stuck: problems specific to this step

   • init says the path alias (@) or Tailwind can't be found
     You may have skipped one of the Tailwind, index.css, tsconfig or vite.config steps above; check them in order and run init again.
   • My project is JavaScript and has no tsconfig file
     The documentation has no instructions for JavaScript or jsconfig. Skip this step; ask the agent to write components to fit the project's existing structure, or get help.
   • The examples on the Vite page show pnpm dlx
     The documentation source and the CLI page also give the npx shadcn@latest form; this guide gives the same command with npx and a pinned version.
   • tsc or the editor shows a deprecation warning about baseUrl
     Remove the baseUrl line and keep only paths; according to the TypeScript announcement, paths works without baseUrl. If you must keep the line, add "ignoreDeprecations": "6.0" next to it.
   Based on: shadcn/ui docs: Vite installation, shadcn-ui/ui: source of the Vite installation docs (npx commands and steps), shadcn/ui docs: CLI (init, add, info), npm registry: shadcn (current version 4.22.0), npm registry: tailwindcss and @tailwindcss/vite (4.3.3), TypeScript 6.0 announcement: deprecated baseUrl, vitejs/vite: create-vite@9.2.1 react-ts template (package.json, tsconfig.json)Get help with this step →
7. Step 7 · In the terminal

   Bring the DESIGN.md colors and fonts into the theme

   I finished this step

   What for: Make components come out with your own brand values instead of shadcn's default theme.

   !You check this step yourself; the system should not move past it without your approval.

   1. Limitation: the shadcn documentation doesn't read DESIGN.md, and it doesn't describe in detail which theme variables init writes into src/index.css. So your brand values don't arrive on their own; you have this step done.
   2. The README of the DESIGN.md tool describes a css-tailwind export for Tailwind v4. The command below prints the DESIGN.md values to the terminal as an @theme block. If the output isn't what you expect, ask for help.
   3. Show the output to Claude Code and ask: add this @theme block to src/index.css, link the color and corner radius variables shadcn defines to these values, and don't delete existing settings.
   4. Then open a button in the browser: check whether it's in the brand's primary color and has the corner radius from DESIGN.md.
   Windows · macOS · LinuxFolder: marka-sitesi (or your own project folder)

   › npx -p @google/design.md@0.4.0 designmd export --format css-tailwind DESIGN.mdCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   How you know it worked

   • The terminal prints an @theme block containing CSS variables like --color-*.
   • src/index.css holds these values, and a button appears in the brand's primary color.
   If you get stuck: problems specific to this step

   • The button is still gray or in the default color
     The shadcn variables and the @theme values may be separate; tell the agent to find which variable the button uses and link it to the DESIGN.md value.
   • In Windows PowerShell the command prints nothing
     The README says the direct design.md form may print nothing; that's why the command is written in the -p ... designmd form. Keep the same form.
   Based on: google-labs-code/design.md: repository and README (format, lint command, license), shadcn-ui/ui: source of the Vite installation docs (npx commands and steps)Get help with this step →
8. Step 8 · In a coding agent

   Have two different pages built with the same rules

   I finished this step

   What for: See on two different pages that consistency really works.

   !You check this step yourself; the system should not move past it without your approval.

   1. Write to Claude Code: following the DESIGN.md rules, create the home page and a service page; use the existing components, don't add colors or fonts outside the rules; make the top menu, buttons and headings look the same on both pages.
   2. When it's done, ask for the list of changed files and ask whether any color or font was made up outside DESIGN.md.
   3. Open the pages side by side in the browser: check whether heading sizes, buttons, spacing and colors match on both pages, whether links work and whether form fields are visible.

   How you know it worked

   • Both pages share the same top menu, button and heading style.
   • Menu links move back and forth between the two pages.
   If you get stuck: problems specific to this step

   • The two pages come out with different colors or buttons
     Give the agent a screenshot showing the difference and have it fix the difference according to DESIGN.md; if something is missing from the rules, add it to DESIGN.md first.
   Based on: Claude Code docs: CLAUDE.md and importing files with @, Claude Code docs: quickstart and account typesGet help with this step →
9. Step 9 · In the terminal

   Check in the browser and at 390 pixels wide

   I finished this step

   What for: Make sure no overflow, broken layout or unreadable text remains at phone width.

   !You check this step yourself; the system should not move past it without your approval.

   1. Prerequisite: Google Chrome must be installed on your computer. With the development server running, install Playwright CLI, open the page in Chrome with the commands below, set the window to 390 pixels wide and take a screenshot. According to the documentation, the tool runs without a window by default (headless); if you want to see the window, add --headed to the open command.
   2. Run all three playwright-cli commands (open, resize, screenshot) from the same folder, that is, from inside marka-sitesi. Because the README groups sessions by working folder, commands given from different folders may not reach the same session; the README doesn't state this explicitly, so this is a precaution.
   3. Run the commands one after another: the README says a headless session shuts down on its own when it receives no commands and has to be restarted with the open command.
   4. Open the saved image and check in the file properties that the width is 390 pixels. If it's different, try the open --mobile or open --device="iPhone 15" options from the README.
   5. In the image, check whether text runs off the edge, whether buttons are big enough to tap with a finger and whether images go off screen. If there's a problem, give the image to the agent and have it fixed; after each fix, take a new image with the same command.
   Windows · macOS · LinuxFolder: Any folder

   › npm install -g @playwright/cli@0.1.22Copy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   Windows · macOS · LinuxFolder: marka-sitesi (or your own project folder); all three commands in the same folder

   › playwright-cli open http://localhost:5173 --browser=chromeCopy

   Windows · macOS · LinuxFolder: marka-sitesi (or your own project folder); all three commands in the same folder

   › playwright-cli resize 390 844Copy

   Windows · macOS · LinuxFolder: marka-sitesi (or your own project folder); all three commands in the same folder

   › playwright-cli screenshot --filename=mobile-home-page.pngCopy

   How you know it worked

   • A mobile-home-page.png file is created in the folder where you ran the commands, and it is 390 pixels wide.
   • In the image, text and buttons stay within the screen width.
   If you get stuck: problems specific to this step

   • The address in the open command doesn't open
     Use the address Vite printed to the terminal; 5173 is an example, and your server may have picked a different port.
   • The browser doesn't open, or there's a not-found error
     The README doesn't cover this error or a browser download step. Make sure Chrome is installed on your computer and use the --browser=chrome option in the open command.
   • The screenshot command gives an error like session not found
     Per the documentation, a headless session closes when it sits idle; run the open command again, then give the resize and screenshot commands one after another.
   • A horizontal scrollbar appears
     Along with the screenshot, ask the agent which element overflows the screen; it's usually a fixed-width image or table.
   Based on: microsoft/playwright-cli: README (open, resize, screenshot), npm registry: @playwright/cli (current version 0.1.22)Get help with this step →

What you pay for

The items are separate, not a total; which ones you need depends on the path you set up. Prices change, so check the source of each item.

• SubscriptionClaude Code access

  According to the documentation, it requires a Claude Pro, Max, Team or Enterprise subscription, a Claude Console account or a cloud provider. See Anthropic's pricing page for current plan terms and prices. source

• SubscriptionRefero MCP (optional)

  The free plan has no MCP access; MCP requires a paid plan. Current prices are on Refero's pricing page. source

• No costDESIGN.md lint tool, shadcn command, Playwright CLI, Vite

  These are openly licensed software (the DESIGN.md repository is Apache-2.0, the Awesome DESIGN.md repository MIT, shadcn and Vite MIT, Playwright CLI Apache-2.0); they need no separate subscription to install. source

• HostingSite publishing and hosting

  This guide doesn't cover publishing the site; hosting and a domain for publishing are a separate cost item. source

• Setup serviceSetup support

  If you like, we can handle the brand/design system prep, component implementation and site development for you; scope is agreed on a call. source

Sources

• google-labs-code/design.md: repository and README (format, lint command, license) · Source code · read October 17, 2026
• DESIGN.md spec (docs/spec.md, version: alpha) · Source code · read October 17, 2026
• npm registry: @google/design.md (current version 0.4.0) · Vendor page · read October 17, 2026
• getdesign.md Terms (use of the DESIGN.md files in the directory) · Official documentation · read October 17, 2026
• VoltAgent/awesome-design-md: README and license note · Source code · read October 17, 2026
• Claude Code docs: CLAUDE.md and importing files with @ · Official documentation · read October 17, 2026
• Claude Code docs: installing plugins · Official documentation · read October 17, 2026
• Claude Code docs: quickstart and account types · Official documentation · read October 17, 2026
• anthropics/claude-plugins-official: marketplace.json (frontend-design entry) · Source code · read October 17, 2026
• anthropics/claude-code: frontend-design plugin README · Source code · read October 17, 2026
• shadcn/ui docs: Vite installation · Official documentation · read October 17, 2026
• shadcn/ui docs: CLI (init, add, info) · Official documentation · read October 17, 2026
• npm registry: shadcn (current version 4.22.0) · Vendor page · read October 17, 2026
• Vite docs: getting started and Node.js requirement · Official documentation · read October 17, 2026
• npm registry: create-vite (current version 9.2.1) · Vendor page · read October 17, 2026
• microsoft/playwright-cli: README (open, resize, screenshot) · Source code · read October 17, 2026
• npm registry: @playwright/cli (current version 0.1.22) · Vendor page · read October 17, 2026
• Refero docs: plans · Help center · read October 17, 2026
• Refero docs: MCP getting started · Official documentation · read October 17, 2026
• Refero Terms of Use: use of Refero content · Official documentation · read October 17, 2026
• vitejs/vite: create-vite source code (options: --template, --immediate, --interactive) · Source code · read October 17, 2026
• shadcn-ui/ui: source of the Vite installation docs (npx commands and steps) · Source code · read October 17, 2026
• npm registry: tailwindcss and @tailwindcss/vite (4.3.3) · Vendor page · read October 17, 2026
• Refero docs: MCP tools (Styles) · Official documentation · read October 17, 2026
• TypeScript 6.0 announcement: deprecated baseUrl · Official documentation · read October 17, 2026
• vitejs/vite: create-vite@9.2.1 react-ts template (package.json, tsconfig.json) · Source code · read October 17, 2026