ai-react-ui/README.md

An AI-friendly React UI component library

# AI React UI

A React UI component library specifically designed for AI code generation. This library provides a simple, consistent, and predictable API that makes it easy for AI systems to generate correct and maintainable React code.

## Why AI-Friendly?

- **Consistent Naming**: Components and props follow predictable naming patterns
- **Simple API**: Minimal props with sensible defaults
- **Type Safety**: Full TypeScript support for better AI code generation
- **Predictable Behavior**: Components behave consistently across different use cases
- **Clear Documentation**: Each component has a simple, example-based documentation

## Quick Start

```tsx
import { ThemeProvider, Button, Card, Text } from "ai-react-ui";

function App() {
  return (
    <ThemeProvider>
      <Card padding="medium">
        <Text>Hello World!</Text>
        <Button>Click me</Button>
      </Card>
    </ThemeProvider>
  );
}
```

## Component API Reference

### Button

```tsx
// Basic usage
<Button>Click me</Button>

// With variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>

// With sizes
<Button size="small">Small</Button>
<Button size="medium">Medium</Button>
<Button size="large">Large</Button>

// Full width
<Button fullWidth>Full Width</Button>
```

### Card

```tsx
// Basic usage
<Card>Content</Card>

// With padding
<Card padding="small">Small Padding</Card>
<Card padding="medium">Medium Padding</Card>
<Card padding="large">Large Padding</Card>

// With elevation
<Card elevation="none">No Shadow</Card>
<Card elevation="small">Small Shadow</Card>
<Card elevation="medium">Medium Shadow</Card>
<Card elevation="large">Large Shadow</Card>
```

### Text

```tsx
// Basic usage
<Text>Hello World</Text>

// With sizes
<Text size="small">Small Text</Text>
<Text size="medium">Medium Text</Text>
<Text size="large">Large Text</Text>

// With weights
<Text weight="normal">Normal Text</Text>
<Text weight="medium">Medium Text</Text>
<Text weight="bold">Bold Text</Text>

// With custom color
<Text color="#FF0000">Red Text</Text>
```

## Theme System

The library includes a built-in theme system with light and dark modes:

```tsx
import { ThemeProvider, useTheme } from "ai-react-ui";

// Basic theme usage
<ThemeProvider>
  <YourApp />
</ThemeProvider>

// Start with dark theme
<ThemeProvider initialMode="dark">
  <YourApp />
</ThemeProvider>

// Theme switching
function ThemeSwitcher() {
  const { mode, toggleTheme } = useTheme();
  return (
    <Button onClick={toggleTheme}>
      Switch to {mode === "light" ? "Dark" : "Light"} Mode
    </Button>
  );
}

// Custom theme
const customTheme = {
  colors: {
    primary: "#FF0000",
    // ... other color overrides
  },
};

<ThemeProvider theme={customTheme}>
  <YourApp />
</ThemeProvider>
```

## Type Definitions

All components are fully typed with TypeScript:

```tsx
// Button props
interface ButtonProps {
  variant?: "primary" | "secondary" | "outline";
  size?: "small" | "medium" | "large";
  fullWidth?: boolean;
  children: React.ReactNode;
}

// Card props
interface CardProps {
  padding?: "small" | "medium" | "large";
  elevation?: "none" | "small" | "medium" | "large";
  children: React.ReactNode;
}

// Text props
interface TextProps {
  size?: "small" | "medium" | "large";
  weight?: "normal" | "medium" | "bold";
  color?: string;
  children: React.ReactNode;
}
```

## Best Practices for AI Code Generation

1. **Always wrap your app with ThemeProvider**

```tsx
<ThemeProvider>
  <YourApp />
</ThemeProvider>
```

2. **Use consistent prop ordering**

```tsx
<Button variant="primary" size="medium" fullWidth onClick={handleClick}>
  Click me
</Button>
```

3. **Leverage TypeScript for better code generation**

```tsx
// Good: Type-safe props
<Text size="large" weight="bold">Hello</Text>

// Avoid: Invalid props
<Text size="huge" weight="extra-bold">Hello</Text> // TypeScript error
```

4. **Use theme system for consistent styling**

```tsx
const { theme } = useTheme();
// Use theme values for custom styling
<div style={{ color: theme.colors.primary }}>Custom styled content</div>;
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT