{"_id":"@cognivo/design-advisor","name":"@cognivo/design-advisor","dist-tags":{"latest":"0.5.0"},"versions":{"0.5.0":{"name":"@cognivo/design-advisor","version":"0.5.0","description":"184 cognitive bias cards + advisor APIs (incl. gen-ui BiasCatalog adapter) for behaviorally-aware design.","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./registry":{"types":"./dist/utils/bias-registry.d.ts","import":"./dist/registry.js"},"./atlas":{"types":"./dist/atlas/index.d.ts","import":"./dist/atlas.js"},"./components":{"import":"./dist/components.js"},"./categories/*":{"import":"./dist/categories/*.js"},"./categories/perception":{"import":"./dist/categories/perception.js"},"./categories/decision-making":{"import":"./dist/categories/decision-making.js"},"./categories/memory":{"import":"./dist/categories/memory.js"},"./categories/social":{"import":"./dist/categories/social.js"},"./categories/attribution":{"import":"./dist/categories/attribution.js"},"./categories/emotional":{"import":"./dist/categories/emotional.js"},"./categories/cognitive":{"import":"./dist/categories/cognitive.js"}},"license":"MIT","author":{"name":"Cognivo"},"sideEffects":["./dist/components.js"],"repository":{"type":"git","url":"git+https://github.com/murisd/cognivo.git","directory":"packages/design-advisor"},"homepage":"https://cognivo.dev","bugs":{"url":"https://github.com/murisd/cognivo/issues"},"publishConfig":{"access":"public"},"dependencies":{"@quietloudlab/ai-interaction-atlas":"^1.0.10","lit":"^3.1.0","@cognivo/core":"0.4.0"},"devDependencies":{"@types/node":"^20.11.0","typescript":"^5.3.3","vite":"^6.4.1","vite-plugin-dts":"^4.3.0","vitest":"^2.1.0"},"keywords":["cognivo","design-system","ui","components","cognitive-bias","behavioral-science"],"scripts":{"build":"vite build && tsc --emitDeclarationOnly","dev":"vite build --watch","test":"vitest run","test:watch":"vitest","bench":"vitest bench","type-check":"tsc --noEmit"},"_id":"@cognivo/design-advisor@0.5.0","_integrity":"sha512-UJ7zmr+9V/IgECs9SxU8zpXHawDu17u1PAry5nbr7nxEvrJBUakssVIJ3XXnW9MtMs8ejtecxAX1wnsOzfWlPQ==","_resolved":"/private/var/folders/ts/mj917p251k38v_z025z2d8ww0000gn/T/d4f631e842071513caee221c8aadbfce/cognivo-design-advisor-0.5.0.tgz","_from":"file:cognivo-design-advisor-0.5.0.tgz","_nodeVersion":"25.8.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-UJ7zmr+9V/IgECs9SxU8zpXHawDu17u1PAry5nbr7nxEvrJBUakssVIJ3XXnW9MtMs8ejtecxAX1wnsOzfWlPQ==","shasum":"c24d7b428f50288d3b423800ae53f4415bc3effe","tarball":"https://registry.npmjs.org/@cognivo/design-advisor/-/design-advisor-0.5.0.tgz","fileCount":45,"unpackedSize":20291610,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHMT0T6xJ5Zbm7yrfbdNSjbM1oQe4iMJOho1kzS6XImoAiEA5amGT5SqpAgGKO/fLQx6ZYPuXAbR4D4iQoP1rmcxZss="}]},"_npmUser":{"name":"muriloscigliano","email":"dev@murilo.design"},"directories":{},"maintainers":[{"name":"muriloscigliano","email":"dev@murilo.design"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/design-advisor_0.5.0_1778028472262_0.34063979084204554"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-06T00:47:52.168Z","0.5.0":"2026-05-06T00:47:52.585Z","modified":"2026-05-06T00:47:52.804Z"},"maintainers":[{"name":"muriloscigliano","email":"dev@murilo.design"}],"description":"184 cognitive bias cards + advisor APIs (incl. gen-ui BiasCatalog adapter) for behaviorally-aware design.","homepage":"https://cognivo.dev","keywords":["cognivo","design-system","ui","components","cognitive-bias","behavioral-science"],"repository":{"type":"git","url":"git+https://github.com/murisd/cognivo.git","directory":"packages/design-advisor"},"author":{"name":"Cognivo"},"bugs":{"url":"https://github.com/murisd/cognivo/issues"},"license":"MIT","readme":"# @cognivo/design-advisor\n\n**Cognitive Psychology-Based Design Analysis System**\n\nA comprehensive library of 180 cognitive biases for UX/UI design analysis, powered by AI.\n\n---\n\n## 🎯 Purpose\n\nThis package provides **cognitive bias cards** as a knowledge base for AI agents to analyze and improve design decisions. Each bias card teaches the AI how to detect, analyze, and provide recommendations for cognitive biases in user interfaces.\n\n**This is NOT a design reference tool for humans** (though it can be used that way). It's primarily an **AI knowledge base** that enables intelligent design analysis.\n\n---\n\n## 📊 Status\n\n- **Phase 1**: 5/5 biases ✅ COMPLETE\n- **Phase 2**: 0/20 biases 🔜 NEXT\n- **Overall**: 5/180 biases (2.8%)\n\n---\n\n## 🧠 Completed Biases (Phase 1)\n\n### Critical Impact Biases\n\n1. **Anchoring Bias** - First impressions and reference points\n   - How initial information influences subsequent judgments\n   - Example: First price shown becomes the reference point\n\n2. **Loss Aversion** - Fear of losing vs. desire to gain\n   - People fear losses 2x more than they value gains\n   - Example: \"Don't lose your progress\" vs \"Save your progress\"\n\n3. **Social Proof** - Following others' actions\n   - People look to others' behavior to guide their own\n   - Example: \"23 people are viewing this\" or \"5,000+ reviews\"\n\n4. **Von Restorff Effect** - Distinctive items stand out\n   - Items that stand out are remembered better (isolation effect)\n   - Example: Bright CTA button among neutral elements\n\n5. **Framing Effect** - How presentation affects decisions\n   - Same information, different wording, different outcomes\n   - Example: \"90% success rate\" vs \"10% failure rate\"\n\n---\n\n## 🏗️ Architecture\n\n### Bias Card Structure\n\nEach bias implements a comprehensive 11-section interface:\n\n```typescript\ninterface BiasCard {\n  metadata: {\n    id, name, aliases, category, relatedCategories, tags\n  };\n\n  definition: {\n    simple, detailed, psychologyBasis, realWorldExample\n  };\n\n  designImpact: {\n    description, whenToUse, whenToAvoid, commonMistakes,\n    impactAreas: { layout, typography, color, interaction, content, accessibility }\n  };\n\n  examples: {\n    good, bad, realWorld, abTests\n  };\n\n  detection: {\n    visualCues, patterns, checklistQuestions\n  };\n\n  intent: Intent<BiasAnalysisInput, BiasAnalysisOutput>; // 🔑 AI ANALYSIS\n\n  guidelines: {\n    implementation, dos, donts, bestPractices, accessibility, ethics\n  };\n\n  resources: {\n    papers, books, articles, videos, demos\n  };\n\n  relationships: {\n    complements, conflicts, confusedWith, hierarchy\n  };\n}\n```\n\n### AI Intent System\n\nThe **most important** part of each bias card is the `intent` section:\n\n```typescript\nintent: {\n  systemPrompt: `You are an expert in cognitive psychology and UX design...\n\n  Analyze the provided design for [bias name]. Identify:\n  1. Pattern 1\n  2. Pattern 2\n  3. Pattern 3\n  ...`,\n\n  outputSchema: {\n    detected: boolean,\n    confidence: number,\n    locations: [...],\n    recommendations: [...]\n  }\n}\n```\n\nThis teaches the AI **how to analyze** designs for this specific bias.\n\n---\n\n## 📦 Installation\n\n```bash\n# From workspace root\npnpm install\n\n# Build\ncd packages/design-advisor\npnpm build\n```\n\n---\n\n## 🚀 Usage\n\n### Import Biases\n\n```typescript\nimport {\n  anchoringBias,\n  lossAversion,\n  socialProof,\n  vonRestorffEffect,\n  framingEffect,\n} from '@cognivo/design-advisor';\n\nconsole.log(anchoringBias.definition.simple);\n// \"People rely heavily on the first piece of information...\"\n```\n\n### Query Registry\n\n```typescript\nimport { registry, queryBiases, recommendBiases } from '@cognivo/design-advisor';\n\n// Get all biases\nconst all = registry.getAll();\n\n// Search by term\nconst pricingBiases = queryBiases({\n  searchTerm: 'price',\n  limit: 5\n});\n\n// Filter by category\nconst perceptionBiases = queryBiases({\n  categories: ['perception']\n});\n\n// Get recommendations for context\nconst recommendations = recommendBiases({\n  designType: 'web',\n  userGoals: ['conversion', 'engagement'],\n  industry: 'ecommerce'\n});\n```\n\n### Use Components\n\n```html\n<!DOCTYPE html>\n<html>\n<head>\n  <title>Bias Library</title>\n</head>\n<body>\n  <!-- Browse all biases -->\n  <bias-library></bias-library>\n\n  <!-- Display single bias -->\n  <bias-card id=\"card\"></bias-card>\n\n  <script type=\"module\">\n    import '@cognivo/design-advisor/components';\n    import { anchoringBias } from '@cognivo/design-advisor';\n\n    document.getElementById('card').bias = anchoringBias;\n  </script>\n</body>\n</html>\n```\n\n---\n\n## 🧪 Test & Demo\n\n```bash\n# Start HTTP server\nnpx http-server -p 5173 -c-1 --cors\n\n# Open demo\nopen http://127.0.0.1:5173/packages/design-advisor/test.html\n```\n\n**Demo Features**:\n- Browse all biases\n- Search and filter\n- View detailed information\n- See examples and detection patterns\n- Multiple view modes (Grid, Compact, List)\n\n---\n\n## 📁 File Structure\n\n```\npackages/design-advisor/\n├── src/\n│   ├── biases/\n│   │   ├── core/\n│   │   │   └── types.ts           # Gold standard BiasCard interface\n│   │   ├── anchoring-bias/\n│   │   │   └── index.ts           # 1,200+ lines\n│   │   ├── loss-aversion/\n│   │   │   └── index.ts           # 800+ lines\n│   │   ├── social-proof/\n│   │   │   └── index.ts           # 800+ lines\n│   │   ├── von-restorff-effect/\n│   │   │   └── index.ts           # 700+ lines\n│   │   ├── framing-effect/\n│   │   │   └── index.ts           # 700+ lines\n│   │   └── index.ts               # Exports + registry\n│   ├── utils/\n│   │   └── bias-registry.ts       # Advanced querying\n│   ├── components/\n│   │   ├── bias-card.ts           # Display component\n│   │   ├── bias-library.ts        # Browse component\n│   │   └── index.ts\n│   └── index.ts                   # Main entry point\n├── dist/                          # Build output\n├── test.html                      # Interactive demo\n├── MASTER_PLAN.md                 # 4-phase build strategy\n├── BIAS_INDEX.md                  # Catalog of 180 biases\n└── README.md                      # This file\n```\n\n---\n\n## 🎯 Next Steps (Phase 2)\n\nBuild next 20 high-impact biases:\n\n1. Attentional Bias\n2. Change Blindness\n3. Context Effect\n4. Priming\n5. Picture Superiority Effect\n6. Processing Difficulty Effect\n7. Salience Bias\n8. Selective Perception\n9. Spacing Effect\n10. Illusory Truth Effect\n11. Reciprocity Norm\n12. Authority Bias\n13. In-Group Bias\n14. Conformity\n15. Commitment Bias\n16. Cognitive Dissonance\n17. Dunning–Kruger Effect\n18. False Consensus Effect\n19. Fundamental Attribution Error\n20. Self-Serving Bias\n\nSee `MASTER_PLAN.md` for complete roadmap.\n\n---\n\n## 📚 Resources\n\n### Planning Documents\n- **MASTER_PLAN.md** - Complete 4-phase build strategy\n- **BIAS_INDEX.md** - Searchable catalog of all 180 biases\n\n### Type System\n- **src/biases/core/types.ts** - Complete TypeScript interfaces\n\n### Components\n- **src/components/bias-card.ts** - Interactive bias display\n- **src/components/bias-library.ts** - Full library browser\n\n---\n\n## 🔧 API Reference\n\n### Main Exports\n\n```typescript\n// Biases\nexport {\n  anchoringBias,\n  lossAversion,\n  socialProof,\n  vonRestorffEffect,\n  framingEffect,\n}\n\n// Registry\nexport {\n  BiasRegistry,\n  registry,\n  getAllBiases,\n  getBiasById,\n  queryBiases,\n  recommendBiases,\n  getStatistics,\n}\n\n// Types\nexport type {\n  BiasCard,\n  Intent,\n  BiasAnalysisInput,\n  BiasAnalysisOutput,\n  // ... (30+ types)\n}\n\nexport {\n  BiasCategory,\n  ImpactLevel,\n}\n\n// Components\nexport {\n  BiasCardElement,\n  BiasLibraryElement,\n}\n\n// Metadata\nexport const VERSION = '0.0.1';\nexport const LIBRARY_INFO = { ... };\n```\n\n### BiasCategory Enum\n\n```typescript\nenum BiasCategory {\n  PERCEPTION = 'perception',\n  DECISION_MAKING = 'decision-making',\n  MEMORY = 'memory',\n  SOCIAL = 'social',\n  ATTRIBUTION = 'attribution',\n  EMOTIONAL = 'emotional',\n  COGNITIVE = 'cognitive',\n}\n```\n\n### ImpactLevel Enum\n\n```typescript\nenum ImpactLevel {\n  CRITICAL = 'critical',\n  HIGH = 'high',\n  MEDIUM = 'medium',\n  LOW = 'low',\n}\n```\n\n---\n\n## 🎨 Component Props\n\n### `<bias-card>`\n\n```typescript\ninterface BiasCardElement {\n  bias?: BiasCard;      // The bias to display\n  compact?: boolean;    // Compact view mode (default: false)\n}\n```\n\n### `<bias-library>`\n\nNo props - fully self-contained with internal state management.\n\n**Features**:\n- Search by name, alias, tag\n- Filter by category and impact level\n- View modes: Grid, Compact, List\n- Statistics dashboard\n\n---\n\n## 🧪 Testing\n\n```bash\n# Type check\npnpm type-check\n\n# Build\npnpm build\n\n# Verify build output\nls -lh dist/\n```\n\n---\n\n## 📊 Statistics\n\n```typescript\nimport { getStatistics } from '@cognivo/design-advisor';\n\nconst stats = getStatistics();\nconsole.log(stats);\n/*\n{\n  total: 5,\n  byCategory: {\n    perception: 2,\n    'decision-making': 2,\n    social: 1,\n    // ...\n  },\n  byImpact: {\n    critical: 30,\n    high: 0,\n    medium: 0,\n    low: 0\n  },\n  totalTags: 47,\n  tags: ['pricing', 'first-impression', ...],\n  phase1Complete: 5,\n  totalPlanned: 180,\n  percentComplete: '2.8%'\n}\n*/\n```\n\n---\n\n## 🤝 Contributing\n\nWhen adding new biases:\n\n1. Copy an existing bias as template (e.g., `anchoring-bias/index.ts`)\n2. Follow the complete `BiasCard` interface - **NO SHORTCUTS**\n3. Fill all 11 sections comprehensively\n4. Add to `src/biases/index.ts` exports\n5. Update `BIAS_INDEX.md` progress\n6. Build and test\n\n**Quality Standard**: Each bias should be 700-1200 lines with:\n- Detailed definitions\n- Real-world examples\n- A/B test results\n- Detection patterns\n- AI intent configuration\n- Implementation guidelines\n- Academic resources\n\n---\n\n## 📄 License\n\nPart of the Cognivo project.\n\n---\n\n## 🎉 Achievements\n\n- ✅ Complete type system\n- ✅ 5 exemplar bias cards (gold standard)\n- ✅ Advanced registry system\n- ✅ Interactive components\n- ✅ Comprehensive planning docs\n- ✅ All builds passing\n- ✅ Zero TypeScript errors\n\n**Phase 1: COMPLETE** 🎊\n\nNext: Build 20 high-impact biases (Phase 2)\n","readmeFilename":"README.md","_rev":"1-b5ea18e0606d4a10b1aa43a073afe964"}