Design OS

Design OS is a product planning and design tool designed to bridge the gap between a product idea and the final codebase. It provides a structured, guided process to ensure that AI coding agents have a clear specification (a "source of truth") to follow, preventing generic UI or half-implemented features.

The process follows four main stages:

1. Product Planning: Define your product vision, break down your roadmap, and model your data shape.
2. Design System: Select colors, typography, and design your application shell.
3. Section Design: For each feature area, specify requirements, generate sample data, and design the screens.
4. Export: Generate a complete handoff package containing production-ready components for implementation.

The Design OS export provides the UI and requirements, while your implementation agent builds the logic.

Included in Export:

• Finished UI components: Props-based, fully styled, responsive, and dark-mode ready.
• Product requirements: Specs, user flows, and scope definitions.
• Design system tokens: Colors, typography, and CSS custom properties.
• Sample data: sample-data.json showing the expected data shapes.
• UI behavior test specs: tests.md files describing what to test from a user perspective.

You must build:

• Backend and data layer.
• Routing and state management.
• Actual test implementations (Jest, Vitest, Playwright, etc.).
• Fulfilling the data contracts/callbacks defined by the component props.

Design OS is a product planning and design tool designed to bridge the gap between a product idea and a codebase. It uses a guided, structured process to capture product vision, data shapes, and UI designs before implementation begins. This ensures that when you hand off to an AI coding agent, there is a clear specification and source of truth.

The process follows four main stages:

1. Product Planning: Define vision, roadmap, and data models.
2. Design System: Establish colors, typography, and the application shell.
3. Section Design: Specify requirements, generate sample data, and design screens for specific feature areas.
4. Export: Generate a complete handoff package for implementation.

Each section in the export includes a tests.md file. These files provide framework-agnostic instructions for writing tests using a TDD (Test-Driven Development) approach. They describe WHAT to test rather than HOW to test, allowing your coding agent to adapt the instructions to your specific testing framework (e.g., Jest, Vitest, Playwright, Cypress, etc.).

Test instructions typically cover:

• User flow tests: Success and failure paths for key interactions.
• Empty state tests: Verifying the UI when no records exist.
• Component interaction tests: Specific UI elements and behaviors to verify.

When designing screens, components must follow a strict props-based pattern to ensure they are portable and exportable to your final codebase. Components should never import sample data directly; instead, they must receive all necessary data and interaction callbacks through their Props interface.

// Example: Components accept props, never import data directly
export function InvoiceList({
  invoices,
  onView,
  onEdit,
  onDelete,
  onCreate
}: InvoiceListProps) {
  // ...
}

Design OS operates through a structured three-phase sequence using slash commands. Each command initiates a conversation with an AI to shape your product. It is recommended to follow the sequence strictly, as each step builds upon the foundation established in the previous one.

Phase 1: Product Planning

Establish the foundation by defining the product vision, choosing design tokens (colors/typography), and designing the application shell (navigation/layout).

Phase 2: Section Design

Iterate through your product roadmap by shaping individual sections (scope/requirements/data), designing the actual React components for those screens, and optionally capturing screenshots.

Phase 3: Export

Generate the final handoff package once all sections are complete.

If you want to build the entire product in a single session:

1. Open product-plan/prompts/one-shot-prompt.md.
2. Add any additional notes, such as tech stack preferences or specific constraints.
3. Copy/paste the prompt into your AI coding agent.
4. Answer the agent's clarifying questions regarding authentication, user modeling, etc.
5. Let the agent plan and implement the full scope based on product-overview.md and instructions/one-shot-instructions.md.

To set up a local instance of Design OS, clone the repository, remove the original remote to ensure a clean workspace, install dependencies, and start the development server.

1. Clone the repository:

   git clone https://github.com/buildermethods/design-os.git my-project-design
   cd my-project-design

   (Replace my-project-design with your preferred workspace name).

2. Remove the original remote:

   git remote remove origin

3. Install dependencies:

   npm install

4. Start the dev server:

   npm run dev

   The application will be available at http://localhost:5173.

Exported components are designed to be production-ready, portable, and decoupled from Design OS. They follow a strict props-based pattern: they accept data and callbacks via props and never import data directly.

When implementing, your agent's responsibility is to:

1. Wire up callbacks to your routing and API calls.
2. Replace sample-data.json with real data from your backend.
3. Implement error handling and loading states.
4. Implement empty states.
5. Write tests based on the provided tests.md instructions.

Example of a component usage:

// Components expect data and callbacks as props
<InvoiceList
  invoices={data}
  onView={(id) => navigate(`/invoices/${id}`)}
  onEdit={(id) => navigate(`/invoices/${id}/edit`)}
  onDelete={(id) => confirmDelete(id)}
  onCreate={() => navigate('/invoices/new')}
/>

To run Design OS on your local machine, ensure you have the following installed:

• Node.js: version 18 or higher.
• npm: typically installed alongside Node.js.
• An AI coding assistant: Design OS relies on slash commands to guide the design process. While Claude Code is recommended, you can use any AI coding tool that supports custom commands or prompts (such as Cursor, Windsurf, or Codex).