AI-Ready Design Systems: Building for Human-AI Collaboration

/**
 * @component Button
 * @category Action
 * @aiGuidance {
 *   usage: "Use for primary, secondary, and tertiary actions",
 *   constraints: {
 *     primaryPerScreen: 1,
 *     secondaryPerScreen: "unlimited",
 *     minimumTouchTarget: "44px"
 *   },
 *   when: {
 *     primary: "Main call-to-action (submit, save, next)",
 *     secondary: "Alternative actions (cancel, back)",
 *     tertiary: "Low-emphasis actions (edit, delete)"
 *   },
 *   avoid: [
 *     "Using primary variant for destructive actions",
 *     "Multiple primary buttons in same view",
 *     "Buttons for navigation (use Link instead)"
 *   ],
 *   examples: {
 *     correct: [
 *       "<Button variant='primary'>Submit Form</Button>",
 *       "<Button variant='secondary'>Cancel</Button>"
 *     ],
 *     incorrect: [
 *       "<Button variant='primary'>Delete Account</Button>",
 *       "<Button>Click here</Button>" // No variant specified
 *     ]
 *   }
 * }
 */

/**
 * @component Card
 * @aiGuidance {
 *   composition: {
 *     requiredChildren: ["CardHeader", "CardContent"],
 *     optionalChildren: ["CardFooter", "CardImage"],
 *     forbiddenChildren: ["Card", "Modal", "Dialog"],
 *     childOrder: ["CardImage", "CardHeader", "CardContent", "CardFooter"]
 *   },
 *   contentGuidelines: {
 *     header: "Clear, concise title (4-8 words)",
 *     content: "Descriptive paragraph (2-3 sentences)",
 *     footer: "Action buttons or metadata",
 *     image: "Relevant, high-quality visual"
 *   },
 *   accessibility: {
 *     requiresAriaLabel: false,
 *     roleImplied: "article",
 *     minContrastRatio: 4.5
 *   }
 * }
 */

{
  "brandVoice": {
    "attributes": [
      "professional",
      "approachable",
      "confident",
      "clear"
    ],
    "notAttributes": [
      "casual",
      "overly technical",
      "salesy",
      "condescending"
    ],
    "tone": {
      "default": "helpful and straightforward",
      "success": "encouraging without being patronizing",
      "error": "empathetic and solution-focused",
      "warning": "cautious but not alarmist"
    },
    "vocabulary": {
      "preferred": {
        "users": "people, customers",
        "utilize": "use",
        "purchase": "buy"
      },
      "avoid": [
        "leverage",
        "synergy",
        "disrupt",
        "revolutionary",
        "game-changing"
      ]
    },
    "grammar": {
      "perspective": "second person (you)",
      "activeVoice": true,
      "contractions": "encouraged",
      "oxford comma": true,
      "sentenceLength": "15-20 words average"
    }
  }
}

// Validate component composition at build time
export function validateComponent(tree) {
  const errors = [];

  // Check nesting depth
  const depth = getMaxDepth(tree);
  if (depth > 3) {
    errors.push(`Component nesting too deep: ${depth} levels (max: 3)`);
  }

  // Check for forbidden combinations
  if (hasModal(tree) && hasDrawer(tree)) {
    errors.push('Modal and Drawer cannot be used together');
  }

  // Check for required children
  const cards = findComponents(tree, 'Card');
  cards.forEach(card => {
    if (!hasChild(card, 'CardHeader') || !hasChild(card, 'CardContent')) {
      errors.push(`Card missing required children: CardHeader, CardContent`);
    }
  });

  // Check button constraints
  const primaryButtons = findComponents(tree, 'Button', { variant: 'primary' });
  if (primaryButtons.length > 1) {
    errors.push(`Too many primary buttons: ${primaryButtons.length} (max: 1)`);
  }

  return errors;
}