Design OS runs as a local React application. Follow these steps to get it up and running on your machine.
Prerequisites
Before you begin, make sure you have:
- Node.js (v18 or higher recommended)
- npm (comes with Node.js)
- Git
- Claude Code or another AI coding assistant that supports slash commands
Design OS uses React 19, Vite, and Tailwind CSS v4. The project handles all dependencies automatically—you just need Node.js installed.
Installation Steps
Clone the Repository
Clone Design OS to your local machine. Replace my-project-design with whatever you want to name your design workspace:git clone https://github.com/buildermethods/design-os.git my-project-design
cd my-project-design
Use a descriptive name that reflects the product you’re designing, like saas-dashboard-design or marketplace-app-design.
Remove the Original Remote
Since this is your own design workspace, remove the connection to the original repository:Now you have a clean local instance ready to use. Install Dependencies
Install all required packages:This will install:
- React 19 and React DOM
- Vite (dev server and build tool)
- Tailwind CSS v4
- Radix UI components
- Lucide React icons
- TypeScript and all necessary type definitions
Start the Dev Server
Launch the local development server:Open http://localhost:5173 in your browser to view the Design OS interface. Open Claude Code
In the same project directory, start Claude Code (or your preferred AI coding assistant):You’re ready to start designing! Run /product-vision to begin defining your product. Available Scripts
Design OS includes these npm scripts:
| Script | Command | Purpose |
|--------|---------|---------||
| Development | npm run dev | Start the Vite dev server at http://localhost:5173 |
| Build | npm run build | Compile TypeScript and build for production |
| Preview | npm run preview | Preview the production build locally |
| Lint | npm run lint | Check code for issues using ESLint |
You’ll primarily use npm run dev during the design process. The build and preview commands are mainly for testing.
Optional: Save as Your Own Template
If you plan to use Design OS for multiple projects, you can create your own template repository:
Push to Your GitHub
Create a new repository on GitHub and push your local copy:git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
git push -u origin main
Mark as Template
Go to your repository on GitHub:
- Click Settings
- Check Template repository
Now you can create new instances using GitHub’s “Use this template” button. This is useful if you want to add custom slash commands, modify the Design OS interface, or maintain a team-specific version.
Project Structure
After installation, your Design OS workspace will have this structure:
my-project-design/
├── product/ # Product definition files (generated by slash commands)
│ ├── product-overview.md # Product name, description, features
│ ├── product-roadmap.md # List of sections to build
│ ├── data-shape/ # Data entities and relationships
│ ├── design-system/ # Colors and typography tokens
│ ├── shell/ # Application shell spec
│ └── sections/ # Section specs, data, types, screenshots
│
├── src/ # Design OS application
│ ├── sections/ # Screen design components (exported)
│ ├── shell/ # Shell components (exported)
│ ├── components/ # Design OS UI components
│ ├── pages/ # Design OS pages
│ └── App.tsx # Main application
│
├── product-plan/ # Export package (generated by /export-product)
│ ├── README.md # Quick start guide for implementation
│ ├── prompts/ # Ready-to-use prompts for coding agents
│ ├── instructions/ # Step-by-step implementation guides
│ ├── design-system/ # Exported tokens
│ ├── shell/ # Exported shell components
│ └── sections/ # Exported section components
│
└── package.json # Dependencies and scripts
```bash
<Info>
The `product/` directory contains your design artifacts. The `product-plan/` directory is generated when you run `/export-product` and contains everything needed for implementation.
</Info>
## Troubleshooting
### Port 5173 Already in Use
If you see an error about port 5173 being in use:
```bash
# Kill the process using port 5173
lsof -ti:5173 | xargs kill -9
# Then restart the dev server
npm run dev
```bash
### Changes Not Appearing
If your design changes aren't showing up in the browser:
1. Stop the dev server (Ctrl+C)
2. Restart it: `npm run dev`
3. Hard refresh your browser (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows/Linux)
### Installation Errors
If you encounter errors during `npm install`:
```bash
# Clear npm cache
npm cache clean --force
# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json
# Reinstall
npm install
```bash
<Warning>
Design OS requires Node.js v18 or higher. If you're using an older version, you may encounter compatibility issues. Run `node --version` to check your version.
</Warning>
## Next Steps
Now that Design OS is installed, head over to [Getting Started](/getting-started) to learn the workflow and start designing your first product.