design-os-product-planning

# 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

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

# Development mode
npm run dev
 
# or with bun
bun run dev
 
# Production build
npm run build
npm start

# Start a new design project
npm run dev
 
# Build the project
npm run build
 
# Run tests
npm test
 
# Type checking
npm run type-check

// 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"
  ]
};

// 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]
  }
};

// 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"]
    }
  ]
};

// 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[];
}

// 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";
  };
}

// 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
    }
  ]
};

// 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>
  );
}
`;

// 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;
}
`;

// 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"
  }
};

// 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"
  }
};

// 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" }
  ]
};

// 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
    }
  ]
};

// 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"
};

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"
  ]
};

// 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';"
  }
};

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

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
  }
};

// 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%"
};

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

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"
  }
};

// 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[];
  };
}