@spaced-out/ui-design-system/COMPONENT_PROMPT_TEMPLATE.md

Sense UI components library

# Genesis Design System - Component Implementation Prompt Template

Use this template when creating new components to ensure proper integration with the Genesis Design System MCP server.

---

## Component Implementation Request

### Component Name

**[ComponentName]** (e.g., "TemplateCard", "StatusBadge", "AlertDialog")

### Design Reference

Implement this design from Figma:
@[Figma URL with node-id]

**Additional References (if applicable):**

- Component states: @[Figma URL]
- Component anatomy: @[Figma URL]
- Interactions: @[Figma URL]

---

## Genesis Design System Integration

### 1. Check Similar Components First

Before starting, review existing Genesis components for patterns:

- [List similar components to check, e.g., "Card", "Icon", "Button"]

**Ask:** "What similar components exist in Genesis?"

### 2. Identify Reusable Components & Types

This component will use:

- [ ] Icon component → Query for `IconType`, `IconSize` exports
- [ ] Button component → Query for `ButtonProps`, button variants
- [ ] [Other components] → Check their exported types

**Ask:** "What types does [Component] export?"

### 3. Implementation Checklist

Before implementing:

- [ ] Call `get_css_module_guidelines` for CSS best practices
- [ ] Call `get_component` for each component you'll use (to get exported types)
- [ ] Call `get_design_tokens` for relevant categories (color, space, size, etc.)
- [ ] Review similar component's CSS for state/modifier patterns

---

## Component Specifications

### TypeScript Requirements ⚠️

**IMPORTANT**: Use **pure TypeScript** only. Do NOT use Flow types.

- ❌ **NO** `Flow.AbstractComponent`
- ❌ **NO** `import type {Flow} from 'flow-to-typescript-codemod'`
- ✅ **YES** `React.forwardRef<HTMLDivElement, Props>`

**Correct TypeScript Pattern:**

```typescript
export const ComponentName = React.forwardRef<
  HTMLDivElement,
  ComponentNameProps
>(({prop1, prop2, ...props}, ref) => (
  <div ref={ref} {...props}>
    {/* component content */}
  </div>
));
```

### Props Interface

Define the component props clearly:

```typescript
export interface [ComponentName]Props {
  // List each prop with:
  // - name: type - description
  // - Indicate if using imported types from other components

  classNames?: ClassNames;        // Standard Genesis pattern
  testId?: string;                // Standard Genesis pattern
}
```

**Example:**

```typescript
export interface TemplateCardProps {
  headerColor?: HeaderColorType; // Custom type for this component
  iconName: string; // Use string, render Icon internally
  iconType?: IconType; // ✅ Import from Icon component
  footer?: React.ReactNode; // Flexible content
  children?: React.ReactNode; // Flexible content
}
```

### Component Structure

Describe the component's structure:

1. **[Section Name]**: Description

   - Details about this section
   - Behavior notes

2. **[Another Section]**: Description
   - Details

### Behavior & Interactions

- [Describe interactive behavior]
- [Describe state management]
- [Describe accessibility requirements]

### Content Philosophy

Specify which parts are:

- **Fixed structure** (controlled by component)
- **Flexible content** (user provides via props)

**Important:** Keep all content demonstrations in Storybook stories only, not in the component implementation.

---

## States/Variants

List all component states or variants:

- State 1: Description
- State 2: Description
- Default state

---

## Special Instructions

Any component-specific requirements or constraints:

- [Special requirement 1]
- [Special requirement 2]

---

## Example Implementation

Provide any code examples or patterns to follow:

```typescript
// Example pattern to follow
```

---

## Notes

- **Use TypeScript only** (NO Flow types like `Flow.AbstractComponent`)
- Follow all Genesis Design System patterns (accessible via MCP)
- Use design tokens for all values (no hardcoded pixels/colors)
- Reuse exported types from existing components
- Test all states in Storybook

---

## Why This Template Works

### MCP Server Integration

This template is designed to work with the Genesis MCP server which provides:

- **`get_css_module_guidelines`** - CSS best practices and patterns
- **`get_component`** - Component details including exported types
- **`get_design_tokens`** - Available design tokens by category
- **`get_component_template`** - Template files for new components

### Key Benefits

1. **Pure TypeScript**: All new components use modern TypeScript patterns (no Flow)
2. **Type Reuse**: Automatically discover and import existing types
3. **Pattern Consistency**: Follow established CSS and component patterns
4. **Token Usage**: Use design tokens instead of hardcoded values
5. **Guided Implementation**: Checklist ensures nothing is missed

### Magic Phrases

Include these in your prompts to trigger MCP usage:

- ✅ "Query [Component] for exported types"
- ✅ "Call get_css_module_guidelines before creating CSS"
- ✅ "Compare with [SimilarComponent].module.css for patterns"
- ✅ "Use design tokens (check get_design_tokens)"
- ✅ "Import [Type] from [Component] (don't redefine)"

---

## Quick Start

For any new component:

1. **Discovery Phase:**

   ```
   "What similar components exist in Genesis?"
   "What types does Icon/Button/[Component] export?"
   "Show me CSS Module guidelines"
   "What design tokens are available for colors/spacing/sizes?"
   ```

2. **Fill out this template** with your specific requirements

3. **Provide to AI** with all Figma links and specifications

4. **Review implementation** against Genesis patterns