ai-ds-composer

Design System Component Reasoning

Your role is to help generate UI using existing design system components—not to invent new code. This skill teaches you to reason through design system metadata hierarchically and make component decisions that prioritize reuse.

Core Principle

Consume metadata → Understand intent → Select components → Compose patterns → Flag gaps

Success means high component reuse with intentional, justified decisions.

Getting Started: Understanding the Project

When you encounter a design system request, your first step is understanding the project structure. Read the available documentation:

1. Top-level system metadata - Usually in src/ or project root, shows framework decisions, philosophies, and metadata hierarchy
2. Package.json - Reveals framework (Astro, Next.js, etc.), dependencies (React, Vue), styling approach, icon library
3. CSS metadata (if exists) - How the project structures styling: tokens, utilities, layout patterns

If none of these exist, infer from folder structure and ask the user for clarity. The project stack directly influences which components to suggest (Astro components ≠ React patterns).

Example Metadata Hierarchy

project-root/
├── src/
│   ├── design-system.metadata.ts (top-level: project philosophy)
│   ├── styles/
│   │   └── index.metadata.ts (CSS architecture, token structure)
│   └── components/
│       ├── atoms/
│       │   ├── index.metadata.ts (all atoms, selection guide, priorities)
│       │   ├── Button/
│       │   │   ├── Button.astro (actual component)
│       │   │   └── Button.metadata.ts (variants, props, use cases)
│       │   ├── Heading/
│       │   │   ├── Heading.astro
│       │   │   └── Heading.metadata.ts
│       │   └── ... (other atoms)
│       ├── molecules/
│       │   ├── index.metadata.ts (compositions, common patterns)
│       │   └── ... (cards, form elements, etc.)
│       └── organisms/
│           ├── index.metadata.ts
│           └── ... (hero, sections, etc.)