---
name: mozaic-react-builder
description: Interactive React/TSX component generator with Mozaic Design System. Helps discover, configure, and generate production-ready React components with TypeScript support, proper imports, and installation guidance.
version: 2.0.0
allowed-tools:
  - Bash
---

# Mozaic React Builder

An interactive assistant for building React applications with the Mozaic Design System by ADEO. This skill helps you discover components, understand their props, generate ready-to-use TypeScript/JSX code, and set up installation properly.

## What This Skill Does

1. **Discover Components**: Browse Mozaic React components by category (forms, navigation, feedback, etc.)
2. **Interactive Selection**: Propose component combinations based on your needs
3. **Generate Code**: Create complete React/TSX code with proper imports and TypeScript types
4. **Installation Guidance**: Provide package manager commands and setup instructions
5. **Props Configuration**: Help configure component props with full type safety

## Shell Scripts Used

This skill uses shell scripts to query the local Mozaic database:
- `list-components.sh` - Browse available React components by category
- `get-component.sh` - Get detailed component information (props, events, TypeScript types)
- `generate-component.sh` - Generate React/TSX component code
- `get-install-info.sh` - Get installation commands and imports

Database location: `~/.claude/mozaic.db`

## When to Use This Skill

Use this skill when you:
- Need to build React UI components with Mozaic
- Want to explore available Mozaic components
- Need help with component props and TypeScript types
- Want installation and import guidance
- Are building forms, navigation, modals, or other UI elements
- Need TypeScript-ready React code

## Interactive Workflow

### Step 1: Understanding Your Needs

When you activate this skill, I'll ask:

**"What type of component do you need to build?"**

Common options:
- A) Form (inputs, selects, checkboxes, validation)
- B) Navigation (tabs, breadcrumb, pagination)
- C) Modal/Dialog (overlay, confirmation, form modal)
- D) Button/Action (primary, secondary, with icons)
- E) Layout (cards, containers, grids)
- F) Data Display (tables, lists, badges)
- G) Other (describe your needs)

### Step 2: Browse Available Components

Based on your answer, I'll use the `list-components.sh` script to show relevant components.

**Example**:
```
For forms, Mozaic offers:
- TextInput (text, email, password fields)
- Select (dropdowns with single/multiple selection)
- Checkbox (single or group)
- Radio (radio button groups)
- Toggle (switch control)
- FileUpload (file input with drag-drop)
```

### Step 3: Component Details

I'll use the `get-component.sh` script to show:
- Available props with TypeScript types and defaults
- Events and callbacks
- Component examples
- TypeScript interfaces

**Example**:
```typescript
// TextInput Props Interface
interface TextInputProps {
  value: string;                    // Controlled value
  onChange: (value: string) => void; // Change handler
  label?: string;                   // Field label
  placeholder?: string;             // Placeholder text
  type?: 'text' | 'email' | 'password' | 'number'; // Input type
  disabled?: boolean;               // Disable state
  error?: string;                   // Error message
  required?: boolean;               // Required field
  size?: 's' | 'm' | 'l';          // Size variant
}
```

### Step 4: Propose Component Combinations

I'll suggest 2-3 combinations that work well together:

**Example for "Login Form"**:

**Option 1: Simple Login**
```tsx
import { TextInput, Button } from '@mozaic-ds/react';

function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  return (
    <form>
      <TextInput
        label="Email"
        type="email"
        value={email}
        onChange={setEmail}
      />
      <TextInput
        label="Password"
        type="password"
        value={password}
        onChange={setPassword}
      />
      <Button theme="primary">Login</Button>
    </form>
  );
}
```

**Option 2: Enhanced Login with Validation**
```tsx
import { useState } from 'react';
import { TextInput, Button, Checkbox } from '@mozaic-ds/react';

interface FormErrors {
  email?: string;
  password?: string;
}

function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [rememberMe, setRememberMe] = useState(false);
  const [errors, setErrors] = useState<FormErrors>({});

  const isValid = email && password;

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    // Your submit logic
  };

  return (
    <form onSubmit={handleSubmit}>
      <TextInput
        label="Email"
        type="email"
        value={email}
        onChange={setEmail}
        error={errors.email}
        required
      />
      <TextInput
        label="Password"
        type="password"
        value={password}
        onChange={setPassword}
        error={errors.password}
        required
      />
      <Checkbox
        checked={rememberMe}
        onChange={setRememberMe}
        label="Remember me"
      />
      <Button
        theme="primary"
        disabled={!isValid}
      >
        Login
      </Button>
    </form>
  );
}
```

### Step 5: Refinement & Configuration

You can:
- Choose an option: "I like Option 2"
- Customize: "Add a forgot password link"
- Combine: "Use Option 1 but add TypeScript from Option 2"
- Request changes: "Make the button larger"
- Ask for TypeScript types: "Show me the full type definitions"

### Step 6: Generate Final Code

I'll use the `generate-component.sh` script to create complete code:

```tsx
import { useState, FormEvent } from 'react';
import { TextInput, Button, Checkbox } from '@mozaic-ds/react';
import '@mozaic-ds/react/dist/styles.css';

interface FormData {
  email: string;
  password: string;
  rememberMe: boolean;
}

interface FormErrors {
  email?: string;
  password?: string;
}

export function LoginForm() {
  const [formData, setFormData] = useState<FormData>({
    email: '',
    password: '',
    rememberMe: false
  });
  const [errors, setErrors] = useState<FormErrors>({});

  const isValid = formData.email && formData.password;

  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    // Your submit logic
    console.log('Form submitted:', formData);
  };

  return (
    <form onSubmit={handleSubmit} className="login-form">
      <TextInput
        label="Email"
        type="email"
        placeholder="Enter your email"
        value={formData.email}
        onChange={(value) => setFormData({ ...formData, email: value })}
        error={errors.email}
        required
      />
      <TextInput
        label="Password"
        type="password"
        placeholder="Enter your password"
        value={formData.password}
        onChange={(value) => setFormData({ ...formData, password: value })}
        error={errors.password}
        required
      />
      <Checkbox
        checked={formData.rememberMe}
        onChange={(checked) => setFormData({ ...formData, rememberMe: checked })}
        label="Remember me"
      />
      <Button
        theme="primary"
        size="l"
        disabled={!isValid}
        type="submit"
      >
        Login
      </Button>
    </form>
  );
}
```

```css
/* styles.css */
.login-form {
  display: flex;
  flex-direction: column;
  gap: 1rem;
  max-width: 400px;
}
```

### Step 7: Installation Guidance

I'll use the `get-install-info.sh` script to provide:

**Package Manager Choice**:
- npm
- yarn
- pnpm (default)

**Installation Commands**:
```bash
# Install Mozaic React
pnpm add @mozaic-ds/react

# Install peer dependencies
pnpm add react@^18.0.0 react-dom@^18.0.0

# Install TypeScript (if not already installed)
pnpm add -D typescript @types/react @types/react-dom
```

**Import Setup**:
```tsx
// In your component or App.tsx
import { TextInput, Button } from '@mozaic-ds/react';
import '@mozaic-ds/react/dist/styles.css';
```

**TypeScript Configuration** (tsconfig.json):
```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "strict": true
  }
}
```

## Common Use Cases

### Use Case 1: Contact Form

**User**: "I need a contact form with TypeScript"

**Workflow**:
1. List form components
2. Propose: Name, Email, Message (textarea), Submit button
3. Show validation patterns with TypeScript
4. Generate code with proper types
5. Provide installation commands

### Use Case 2: Navigation Tabs

**User**: "Build tab navigation for dashboard"

**Workflow**:
1. Show navigation components
2. Demonstrate Tabs component
3. Configure tabs with icons and TypeScript
4. Generate code with tab content
5. Provide styling guidance

### Use Case 3: Modal Dialog

**User**: "Confirmation modal for delete action"

**Workflow**:
1. Show feedback components
2. Demonstrate Modal component
3. Configure: title, message, actions with TypeScript
4. Add danger button styling
5. Generate code with controlled visibility

### Use Case 4: Data Table

**User**: "Display user list in a table with TypeScript"

**Workflow**:
1. Show data-display components
2. Demonstrate Table component
3. Configure columns with proper types
4. Add pagination and row actions
5. Generate code with typed data

## Component Categories Reference

### Form Components
- **TextInput**: Text, email, password, number inputs
- **Select**: Dropdown with single/multiple selection
- **Checkbox**: Single checkbox or checkbox group
- **Radio**: Radio button groups
- **Toggle**: Switch control
- **FileUpload**: File input with drag-drop support
- **DatePicker**: Date selection
- **Textarea**: Multi-line text input

### Navigation Components
- **Tabs**: Tab navigation with content panels
- **Breadcrumb**: Hierarchical navigation trail
- **Pagination**: Page navigation controls
- **Stepper**: Multi-step progress indicator

### Feedback Components
- **Modal**: Overlay dialog/modal
- **Toast**: Notification messages
- **Alert**: Inline alerts and warnings
- **ProgressBar**: Progress indication
- **Loader**: Loading spinners

### Action Components
- **Button**: Primary, secondary, tertiary buttons
- **IconButton**: Button with icon only
- **Link**: Styled hyperlinks

### Layout Components
- **Card**: Content container with header/footer
- **Accordion**: Collapsible content sections
- **Divider**: Visual separator

### Data Display Components
- **Table**: Data grid with sorting/filtering
- **Badge**: Status indicators
- **Tag**: Labeled items
- **Avatar**: User profile images

## Best Practices

### 1. Use TypeScript for Type Safety
```tsx
// Good: Define interfaces for your data
interface User {
  id: number;
  name: string;
  email: string;
}

interface UserFormProps {
  user?: User;
  onSubmit: (user: User) => void;
}

function UserForm({ user, onSubmit }: UserFormProps) {
  // Component implementation
}
```

### 2. Controlled Components
```tsx
// Good: Use controlled components
const [value, setValue] = useState('');

<TextInput
  value={value}
  onChange={setValue}
  label="Username"
/>

// Avoid: Uncontrolled components
<TextInput defaultValue="username" />
```

### 3. Proper Event Handling
```tsx
// Good: Type your event handlers
const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
  event.preventDefault();
  // Your logic
};

<Button onClick={handleClick}>Submit</Button>
```

### 4. Component Composition
```tsx
// Good: Compose components
function UserCard({ user }: { user: User }) {
  return (
    <Card>
      <Card.Header>
        <h2>{user.name}</h2>
      </Card.Header>
      <Card.Body>
        <TextInput value={user.email} readOnly />
      </Card.Body>
      <Card.Footer>
        <Button theme="primary">Edit</Button>
      </Card.Footer>
    </Card>
  );
}
```

### 5. Use React Hooks Properly
```tsx
// Good: Use hooks for state and effects
import { useState, useEffect, useCallback } from 'react';

function FormComponent() {
  const [data, setData] = useState<FormData>({});

  const handleSubmit = useCallback(() => {
    // Submit logic
  }, [data]);

  useEffect(() => {
    // Side effects
  }, []);
}
```

### 6. Props Destructuring with Types
```tsx
// Good: Destructure props with types
interface ButtonProps {
  label: string;
  onClick: () => void;
  disabled?: boolean;
}

function CustomButton({ label, onClick, disabled = false }: ButtonProps) {
  return <Button onClick={onClick} disabled={disabled}>{label}</Button>;
}
```

## TypeScript Patterns

### Generic Components
```tsx
interface SelectOption<T> {
  value: T;
  label: string;
}

interface TypedSelectProps<T> {
  options: SelectOption<T>[];
  value: T;
  onChange: (value: T) => void;
}

function TypedSelect<T>({ options, value, onChange }: TypedSelectProps<T>) {
  // Implementation
}
```

### Form State Management
```tsx
type FormState<T> = {
  values: T;
  errors: Partial<Record<keyof T, string>>;
  touched: Partial<Record<keyof T, boolean>>;
};

function useFormState<T>(initialValues: T) {
  const [state, setState] = useState<FormState<T>>({
    values: initialValues,
    errors: {},
    touched: {}
  });

  // Form logic
  return state;
}
```

## Troubleshooting

### Issue: TypeScript errors with props

**Solution**: Check prop types
```bash
# Use get-component.sh to verify prop types
./scripts/get-component.sh TextInput
```

### Issue: Styles not applying

**Solution**: Import CSS
```tsx
import '@mozaic-ds/react/dist/styles.css';
```

### Issue: Components not rendering

**Solution**: Check React version compatibility
```bash
pnpm list react react-dom
# Should be ^18.0.0 or higher
```

### Issue: Event handlers not working

**Solution**: Use correct callback signatures
```tsx
// Check component docs for callback types
onChange={(value: string) => handleChange(value)}
```

## Commands

When this skill is active:

- **"Show me [category] components"**: Browse components by category
- **"I need a [type]"**: Build specific component type
- **"How do I configure [component]?"**: Get component details with TypeScript
- **"Generate code for [description]"**: Create TypeScript component code
- **"Install instructions"**: Get setup guidance
- **"Show TypeScript examples"**: See typed usage examples
- **"What are the types for [component]?"**: Get TypeScript interfaces

## Integration with Other Skills

This skill works well with:
- **mozaic-design-tokens**: Get color/spacing tokens for styling
- **mozaic-css-utilities**: Add layout utilities (Flexy grid, spacing)
- **mozaic-icons**: Add icons to buttons and components

## Example Session

**User**: "I need a registration form with TypeScript"

**Skill**:
I'll help you build a registration form with Mozaic React components and full TypeScript support!

What fields do you need?
- A) Basic (name, email, password)
- B) Extended (+ phone, address, terms)
- C) Custom (tell me what fields)

**User**: "B - Extended"

**Skill**:
Perfect! Here's a registration form with extended fields and TypeScript:

[Uses `list-components.sh` and `get-component.sh` scripts]

**Proposed Components**:
1. TextInput (Name)
2. TextInput (Email - type="email")
3. TextInput (Password - type="password")
4. TextInput (Phone - type="tel")
5. Textarea (Address)
6. Checkbox (Terms agreement)
7. Button (Submit - theme="primary")

**TypeScript Interfaces**:
```typescript
interface RegistrationData {
  name: string;
  email: string;
  password: string;
  phone: string;
  address: string;
  termsAccepted: boolean;
}
```

[Uses `generate-component.sh` script]

Here's your complete registration form with TypeScript... [Generated code]

Would you like me to:
- Add validation logic with types?
- Include password confirmation field?
- Add installation instructions?

**User**: "Add installation instructions"

**Skill**:
[Uses `get-install-info.sh` script]

Here's how to install and set up...

---

**Let's build amazing React applications with Mozaic Design System and TypeScript!**
