MCPInstall

design-os-product-planning

by reason-machinesCode Quality & Workflow

Use Design OS to guide product planning, data modeling, design systems, and UI design before implementation

Installs
144
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/design-skills --skill design-os-product-planning
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads design-os-product-planning automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Design OS Product Planning Skill

Skill by ara.so — Design Skills collection.

Design OS is a TypeScript-based product planning and design tool that bridges the gap between product ideas and implementation. It provides a structured, AI-guided process to define product vision, model data, design UI, and export production-ready specifications for coding agents.

What Design OS Does

Design OS solves the "build first, understand later" problem with AI coding tools by establishing a clear design specification before implementation begins. It guides you through:

  1. Product Planning - Vision definition, roadmap breakdown, data modeling
  2. Design System - Color schemes, typography, application shell design
  3. Section Design - Feature requirements, sample data, screen designs
  4. Export - Complete handoff packages for implementation

Installation

Prerequisites

  • Node.js 18+ or Bun runtime
  • Git

Clone and Install

# Clone the repository
git clone https://github.com/buildermethods/design-os.git
cd design-os

# Install dependencies (npm, yarn, pnpm, or bun)
npm install

# or with bun
bun install

Environment Setup

Create a .env file in the project root:

# Required: Your AI provider API key
ANTHROPIC_API_KEY=your_key_here
# or
OPENAI_API_KEY=your_key_here

# Optional: Customize AI model
AI_MODEL=claude-3-5-sonnet-20241022

Reference environment variables in code:

const apiKey = process.env.ANTHROPIC_API_KEY;
const model = process.env.AI_MODEL || 'claude-3-5-sonnet-20241022';

Running Design OS

Start the Application

# Development mode
npm run dev

# or with bun
bun run dev

# Production build
npm run build
npm start

The application will start and guide you through the design process interactively.

Key Commands and Workflow

CLI Commands

# Start a new design project
npm run dev

# Build the project
npm run build

# Run tests
npm test

# Type checking
npm run type-check

The Design Process Flow

Design OS uses a conversational, step-by-step process:

1. Product Planning

Define your product vision and data model:

// Example: Defining a product entity
interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  category: string;
  createdAt: Date;
}

// Example: Planning a roadmap feature
const feature = {
  name: "User Dashboard",
  priority: "high",
  status: "planned",
  requirements: [
    "Display user profile information",
    "Show recent activity",
    "Enable quick actions"
  ]
};

2. Design System Configuration

Set up your visual design language:

// Example: Design system configuration
const designSystem = {
  colors: {
    primary: "#3B82F6",
    secondary: "#8B5CF6",
    accent: "#10B981",
    background: "#F9FAFB",
    text: "#111827"
  },
  typography: {
    fontFamily: "Inter, system-ui, sans-serif",
    scale: {
      h1: "2.5rem",
      h2: "2rem",
      h3: "1.5rem",
      body: "1rem",
      small: "0.875rem"
    }
  },
  spacing: {
    unit: 8, // Base spacing unit in px
    scale: [0, 8, 16, 24, 32, 48, 64]
  }
};

3. Section Design

Design individual features and screens:

// Example: Section specification
interface SectionSpec {
  name: string;
  description: string;
  requirements: string[];
  dataModel: Record<string, any>;
  screens: Screen[];
}

const dashboardSection: SectionSpec = {
  name: "User Dashboard",
  description: "Main user interface after login",
  requirements: [
    "Show user stats",
    "Display recent items",
    "Provide navigation to key features"
  ],
  dataModel: {
    user: {
      id: "string",
      name: "string",
      email: "string",
      stats: {
        totalItems: "number",
        recentActivity: "Activity[]"
      }
    }
  },
  screens: [
    {
      name: "DashboardHome",
      layout: "grid",
      components: ["Header", "StatsCards", "ActivityFeed"]
    }
  ]
};

4. Export and Handoff

Generate implementation-ready specifications:

// Example: Export configuration
const exportConfig = {
  format: "typescript-react", // or "vue", "svelte", etc.
  includeTests: true,
  includeStorybook: true,
  outputPath: "./handoff"
};

// Generated component example
interface HandoffComponent {
  path: string;
  code: string;
  tests?: string;
  story?: string;
  dependencies: string[];
}

Data Modeling Patterns

Entity Definition

// Example: E-commerce data model
interface DataModel {
  entities: {
    User: {
      id: string;
      email: string;
      profile: UserProfile;
      orders: Order[];
    };
    Product: {
      id: string;
      name: string;
      price: number;
      inventory: number;
      category: Category;
    };
    Order: {
      id: string;
      userId: string;
      items: OrderItem[];
      status: "pending" | "completed" | "cancelled";
      total: number;
      createdAt: Date;
    };
  };
  relationships: {
    "User.orders": "Order[]";
    "Order.items": "OrderItem[]";
    "Product.category": "Category";
  };
}

Sample Data Generation

// Example: Generate sample data for design
const sampleData = {
  users: [
    {
      id: "usr_1",
      name: "Sarah Johnson",
      email: "sarah@example.com",
      role: "admin"
    },
    {
      id: "usr_2",
      name: "Mike Chen",
      email: "mike@example.com",
      role: "user"
    }
  ],
  products: [
    {
      id: "prd_1",
      name: "Premium Widget",
      price: 49.99,
      inventory: 120
    }
  ]
};

Component Export Patterns

React Component Export

// Example: Exported component structure
export interface ExportedComponent {
  name: string;
  props: Record<string, string>;
  children?: string[];
}

// Generated component code
const exportedCode = `
import React from 'react';

interface DashboardProps {
  user: User;
  stats: UserStats;
}

export function Dashboard({ user, stats }: DashboardProps) {
  return (
    <div className="dashboard">
      <Header user={user} />
      <StatsGrid stats={stats} />
      <ActivityFeed userId={user.id} />
    </div>
  );
}
`;

Design Token Export

// Example: Export design tokens
const tokens = {
  colors: {
    primary: {
      50: "#EEF2FF",
      500: "#3B82F6",
      900: "#1E3A8A"
    }
  },
  spacing: {
    xs: "0.5rem",
    sm: "1rem",
    md: "1.5rem",
    lg: "2rem",
    xl: "3rem"
  }
};

// Export as CSS variables
const cssVariables = `
:root {
  --color-primary-50: #EEF2FF;
  --color-primary-500: #3B82F6;
  --spacing-xs: 0.5rem;
  --spacing-sm: 1rem;
}
`;

Working with the AI Conversation

Providing Context

// Example: Structuring context for AI
const projectContext = {
  type: "SaaS application",
  target: "B2B productivity tool",
  users: "Teams of 5-50 people",
  keyFeatures: [
    "Project management",
    "Team collaboration",
    "Reporting and analytics"
  ],
  techStack: {
    frontend: "React + TypeScript",
    backend: "Node.js",
    database: "PostgreSQL"
  }
};

Iterating on Designs

The AI guides you through refinements:

  1. Initial concept generation
  2. Review and feedback
  3. Refinement based on requirements
  4. Validation against constraints
  5. Final approval and export

Configuration Options

Project Configuration

// designos.config.ts
export default {
  project: {
    name: "My SaaS App",
    version: "1.0.0",
    outputDir: "./design-handoff"
  },
  ai: {
    provider: "anthropic", // or "openai"
    model: process.env.AI_MODEL,
    temperature: 0.7
  },
  export: {
    format: "typescript-react",
    includeTests: true,
    includeDocumentation: true,
    componentLibrary: "shadcn-ui" // optional
  },
  design: {
    responsive: true,
    darkMode: true,
    accessibility: "WCAG-AA"
  }
};

Common Patterns

Feature Planning Pattern

// Define a feature with clear boundaries
interface Feature {
  id: string;
  name: string;
  description: string;
  userStories: string[];
  acceptance: string[];
  dataRequirements: DataEntity[];
  screens: ScreenDesign[];
}

const userAuthFeature: Feature = {
  id: "feat_auth",
  name: "User Authentication",
  description: "Secure user login and registration",
  userStories: [
    "As a user, I can create an account",
    "As a user, I can log in securely",
    "As a user, I can reset my password"
  ],
  acceptance: [
    "Email validation",
    "Password strength requirements",
    "Session management"
  ],
  dataRequirements: [
    {
      entity: "User",
      fields: ["email", "passwordHash", "createdAt"]
    }
  ],
  screens: [
    { name: "Login", type: "form" },
    { name: "Register", type: "form" },
    { name: "ForgotPassword", type: "form" }
  ]
};

Screen Layout Pattern

// Define screen layouts with components
interface ScreenLayout {
  name: string;
  layout: "single-column" | "sidebar" | "grid" | "dashboard";
  regions: Region[];
}

const dashboardLayout: ScreenLayout = {
  name: "Dashboard",
  layout: "dashboard",
  regions: [
    {
      id: "header",
      component: "AppHeader",
      position: "top",
      height: "fixed"
    },
    {
      id: "sidebar",
      component: "Navigation",
      position: "left",
      width: "240px"
    },
    {
      id: "main",
      component: "DashboardContent",
      position: "center",
      scroll: true
    }
  ]
};

Data Flow Pattern

// Map data flow through the application
interface DataFlow {
  source: string;
  transformations: Transformation[];
  destination: string;
}

const userDataFlow: DataFlow = {
  source: "API:/api/users/{id}",
  transformations: [
    {
      type: "normalize",
      schema: "UserSchema"
    },
    {
      type: "enrich",
      with: "userPreferences"
    }
  ],
  destination: "Component:UserProfile"
};

Troubleshooting

AI Response Issues

Problem: AI generates designs that don't match vision

Solution: Provide more specific context and constraints:

const constraints = {
  must: [
    "Mobile-first responsive design",
    "Maximum 3 clicks to any feature",
    "Support keyboard navigation"
  ],
  mustNot: [
    "No more than 2 modals deep",
    "Avoid horizontal scrolling",
    "No auto-playing media"
  ],
  preferences: [
    "Minimize form fields",
    "Use progressive disclosure",
    "Provide inline help"
  ]
};

Export Issues

Problem: Generated code doesn't match project structure

Solution: Configure export templates:

// Custom export template
const exportTemplate = {
  componentPath: "./src/components/${category}/${name}.tsx",
  testPath: "./src/components/${category}/__tests__/${name}.test.tsx",
  stylePath: "./src/components/${category}/${name}.module.css",
  imports: {
    react: "import React from 'react';",
    types: "import type { ${name}Props } from './types';",
    styles: "import styles from './${name}.module.css';"
  }
};

Data Model Inconsistencies

Problem: Relationships between entities unclear

Solution: Use explicit relationship mapping:

// Define relationships explicitly
const relationshipMap = {
  User: {
    hasMany: ["Order", "Review"],
    belongsTo: ["Organization"],
    hasOne: ["Profile"]
  },
  Order: {
    belongsTo: ["User"],
    hasMany: ["OrderItem"]
  },
  OrderItem: {
    belongsTo: ["Order", "Product"]
  }
};

Incomplete Specifications

Problem: Missing details in handoff package

Solution: Use completion checklist:

const completionChecklist = {
  productPlanning: {
    vision: true,
    roadmap: true,
    dataModel: true,
    relationships: true
  },
  designSystem: {
    colors: true,
    typography: true,
    spacing: true,
    components: true
  },
  sections: {
    requirements: true,
    sampleData: true,
    screens: true,
    interactions: true
  },
  export: {
    components: true,
    tests: true,
    documentation: true,
    assets: true
  }
};

Best Practices

Start with Clear Vision

// Document your vision clearly
const productVision = {
  problem: "Teams struggle to coordinate across tools",
  solution: "Unified workspace for project management",
  target: "Remote teams of 10-100 people",
  differentiator: "Real-time collaboration with AI assistance",
  success: "Teams reduce coordination time by 50%"
};

Iterate in Phases

Work through each Design OS phase completely before moving forward. Don't skip steps.

Use Real Data Examples

Provide realistic sample data to inform better designs:

const realisticSample = {
  user: {
    name: "Alexandra Martinez",
    email: "alex.martinez@company.com",
    role: "Product Manager",
    team: "Product Team Alpha",
    lastActive: "2024-01-15T14:30:00Z"
  }
};

Document Decisions

Capture why decisions were made:

const designDecisions = {
  "dashboard-layout": {
    decision: "Used card-based grid layout",
    reason: "Better scanability for multiple data types",
    alternatives: ["List view", "Kanban board"],
    tradeoffs: "Requires more vertical scrolling"
  }
};

Integration with Coding Agents

Design OS outputs are optimized for AI coding agents:

// Handoff package structure for coding agents
interface HandoffPackage {
  specification: {
    overview: string;
    requirements: Requirement[];
    dataModel: DataModel;
    userFlows: UserFlow[];
  };
  design: {
    system: DesignSystem;
    screens: Screen[];
    components: ComponentSpec[];
    interactions: Interaction[];
  };
  implementation: {
    components: ComponentCode[];
    tests: TestCode[];
    types: TypeDefinitions[];
    documentation: string;
  };
  context: {
    decisions: DesignDecision[];
    constraints: Constraint[];
    dependencies: string[];
  };
}

When handing off to a coding agent, provide the complete package with clear instructions on implementation priorities.

FAQ

What does the design-os-product-planning skill do?

Use Design OS to guide product planning, data modeling, design systems, and UI design before implementation

How do I install design-os-product-planning?

Run npx skills add https://github.com/reason-machines/design-skills --skill design-os-product-planning in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/design-os-product-planning/ (personal) or .claude/skills/design-os-product-planning/ (project).

Which AI agents can use design-os-product-planning?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is design-os-product-planning safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains design-os-product-planning?

It is published by reason-machines in reason-machines/design-skills. It has 144 recorded installs.

More from reason-machines/design-skills

View all →

awesome-claude-design

reason-machines/design-skills

Open the skill to read its SKILL.md instructions.

205 installs

design-md-format

reason-machines/design-skills

Create and validate DESIGN.md files that give AI coding agents structured understanding of design systems through machine-readable tokens and human-readable rationale.

178 installs

open-codesign-ai-design

reason-machines/design-skills

Use Open CoDesign to generate prototypes, slides, and PDFs from prompts with Claude, GPT, Gemini, or local models

AI & Agents175 installs

open-design-ai-prototyping

reason-machines/design-skills

Open the skill to read its SKILL.md instructions.

174 installs

diagram-design-editorial

reason-machines/design-skills

Create editorial-quality diagrams in HTML + SVG matching your brand — architecture, flowcharts, sequences, timelines, quadrants, and 9 more types.

Docs & Writing169 installs

keychron-hardware-design

reason-machines/design-skills

Access and work with Keychron keyboard and mouse industrial design files (STEP, DXF, DWG, PDF) for 135+ models to create compatible accessories, remixes, and modifications.

Docs & Writing167 installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs