# @myorg/ui-library

Modern React component library with TypeScript, Tailwind CSS, and full accessibility support.

[![npm version](https://badge.fury.io/js/%40myorg%2Fui-library.svg)](https://www.npmjs.com/package/@myorg/ui-library)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🎨 **50+ Components** - Buttons, inputs, modals, and more
- 🎯 **TypeScript First** - Full type safety out of the box
- ♿ **Accessible** - WCAG AA compliant, keyboard navigation
- 🌗 **Dark Mode** - Built-in theming system
- 📦 **Tree-shakeable** - Import only what you need
- 🎭 **Customizable** - Tailwind CSS and CSS variables
- 📱 **Responsive** - Mobile-first design

## Installation

```bash
npm install @myorg/ui-library

import { Button, Input } from '@myorg/ui-library'
import '@myorg/ui-library/styles.css'

function App() {
  return (
    <div>
      <Button variant="primary">Click me</Button>
      <Input placeholder="Enter text..." />
    </div>
  )
}

import { Button } from '@myorg/ui-library'

function MyComponent() {
  return (
    <Button
      variant="primary"
      size="lg"
      onClick={() => console.log('Clicked!')}
    >
      Click me
    </Button>
  )
}

import { Button, type ButtonProps } from '@myorg/ui-library'

interface MyButtonProps extends ButtonProps {
  customProp?: string
}

function MyButton({ customProp, ...props }: MyButtonProps) {
  return <Button {...props} />
}

import { ThemeProvider } from '@myorg/ui-library'

function App() {
  return (
    <ThemeProvider theme="dark">
      <YourApp />
    </ThemeProvider>
  )
}

module.exports = {
  content: [
    './node_modules/@myorg/ui-library/dist/**/*.{js,ts,jsx,tsx}',
  ],
  presets: [
    require('@myorg/ui-library/tailwind-preset')
  ],
}

:root {
  --color-primary: 59 130 246;
  --color-secondary: 139 92 246;
  --radius: 0.5rem;
}

### Component README
```markdown
# Button

Versatile button component with multiple variants, sizes, and states.

## Import

```tsx
import { Button } from '@myorg/ui-library'

<Button variant="primary" size="md">
  Click me
</Button>

<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>

<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

<Button disabled>Disabled</Button>
<Button loading>Loading</Button>

<Button>
  <Icon name="plus" />
  Add Item
</Button>

## Storybook Stories

### Basic Component Story
```typescript
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './Button'

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'outline', 'ghost'],
      description: 'Visual style variant',
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg'],
    },
    disabled: {
      control: 'boolean',
    },
    onClick: { action: 'clicked' },
  },
}

export default meta
type Story = StoryObj<typeof Button>

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Click me',
  },
}

export const Secondary: Story = {
  args: {
    variant: 'secondary',
    children: 'Secondary Button',
  },
}

export const Sizes: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </div>
  ),
}

export const WithIcon: Story = {
  args: {
    children: (
      <>
        <PlusIcon />
        Add Item
      </>
    ),
  },
}

export const Loading: Story = {
  args: {
    loading: true,
    children: 'Loading...',
  },
}

export const Disabled: Story = {
  args: {
    disabled: true,
    children: 'Disabled',
  },
}

{/* Button.mdx */}
import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
import * as ButtonStories from './Button.stories'

<Meta of={ButtonStories} />

# Button

Versatile button component for user interactions.

## Overview

The Button component provides a consistent way to trigger actions throughout your application. It supports multiple variants, sizes, and states.

<Canvas of={ButtonStories.Primary} />

## Props

<Controls />

## Variants

Buttons come in four visual styles to indicate different levels of emphasis.

### Primary

Use for the main call-to-action on a page.

<Canvas of={ButtonStories.Primary} />

### Secondary

Use for secondary actions that complement the primary action.

<Canvas of={ButtonStories.Secondary} />

### Outline

Use for tertiary actions or to reduce visual weight.

<Canvas of={ButtonStories.Outline} />

### Ghost

Use for the least visual weight, often in toolbars or menus.

<Canvas of={ButtonStories.Ghost} />

## Sizes

Three sizes are available to fit different contexts.

<Canvas of={ButtonStories.Sizes} />

## States

### Loading

Shows a spinner when an async action is in progress.

<Canvas of={ButtonStories.Loading} />

### Disabled

Prevents interaction when an action is not available.

<Canvas of={ButtonStories.Disabled} />

## With Icons

Icons can be added to provide visual clarity.

<Canvas of={ButtonStories.WithIcon} />

## Accessibility

- Keyboard accessible with Enter and Space keys
- Focus indicator visible
- Disabled state properly communicated to screen readers
- Loading state announced to screen readers

## Best Practices

### ✅ Do

- Use primary buttons for main actions
- Keep button text concise (2-4 words)
- Use loading state for async actions
- Ensure minimum touch target size (44x44px)

### ❌ Don't

- Use too many primary buttons
- Use ambiguous labels like "Click here"
- Nest interactive elements
- Make buttons too small

## Examples

### Form Submission

```tsx
function Form() {
  const [loading, setLoading] = useState(false)

  const handleSubmit = async () => {
    setLoading(true)
    await submitForm()
    setLoading(false)
  }

  return (
    <Button
      variant="primary"
      loading={loading}
      onClick={handleSubmit}
    >
      Submit
    </Button>
  )
}

<div className="flex gap-2">
  <Button variant="primary">Save</Button>
  <Button variant="outline">Cancel</Button>
</div>

### Storybook Configuration
```typescript
// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite'

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y', // Accessibility addon
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  docs: {
    autodocs: 'tag',
  },
}

export default config

/**
 * Button component for user interactions.
 *
 * @example
 * ```tsx
 * <Button variant="primary" onClick={() => alert('Clicked!')}>
 *   Click me
 * </Button>
 * ```
 */
export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  /**
   * Visual style variant
   * @default 'primary'
   */
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost'

  /**
   * Button size
   * @default 'md'
   */
  size?: 'sm' | 'md' | 'lg'

  /**
   * Disables the button and prevents interaction
   * @default false
   */
  disabled?: boolean

  /**
   * Shows loading spinner and disables interaction
   * @default false
   */
  loading?: boolean

  /**
   * Button content
   */
  children: ReactNode

  /**
   * Click event handler
   */
  onClick?: (event: MouseEvent<HTMLButtonElement>) => void
}

// typedoc.json
{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "plugin": ["typedoc-plugin-markdown"],
  "excludePrivate": true,
  "excludeProtected": true,
  "excludeExternals": true,
  "readme": "README.md",
  "categorizeByGroup": true,
  "categoryOrder": [
    "Components",
    "Hooks",
    "Utilities",
    "Types"
  ]
}

# Migration Guide: v1.x to v2.0

## Breaking Changes

### 1. Button Component

#### Removed `color` prop

The `color` prop has been replaced with `variant` for clearer semantics.

**Before (v1.x):**
```tsx
<Button color="blue">Click me</Button>

<Button variant="primary">Click me</Button>

<Button isLoading>Submit</Button>

<Button loading>Submit</Button>

<Input required error="Required field" />

<Input validation={{ required: true, error: "Required field" }} />

import { ThemeProvider } from '@myorg/ui-library'

function App() {
  return (
    <ThemeProvider>
      <YourApp />
    </ThemeProvider>
  )
}

<Select>
  <Select.Trigger>Choose option</Select.Trigger>
  <Select.Content>
    <Select.Item value="1">Option 1</Select.Item>
    <Select.Item value="2">Option 2</Select.Item>
  </Select.Content>
</Select>

// Deprecated (still works but will warn)
<Alert type="error">Error message</Alert>

// Recommended
<Alert variant="error">Error message</Alert>

npx @myorg/ui-library-codemod v1-to-v2 src/

## Documentation Best Practices

### Writing Style
1. **Clear and Concise**: Use simple language
2. **Examples First**: Show code before explaining
3. **Progressive Disclosure**: Basic → Advanced
4. **Consistent Formatting**: Use same patterns
5. **Scannable**: Use headings, lists, tables

### Content Structure
1. **Start with Why**: Explain purpose
2. **Quick Start**: Get users running fast
3. **Common Use Cases**: Cover 80% of usage
4. **API Reference**: Complete prop documentation
5. **Troubleshooting**: Address common issues

### Code Examples
1. **Complete**: Copy-paste ready
2. **Realistic**: Real-world scenarios
3. **Commented**: Explain non-obvious parts
4. **TypeScript**: Show type usage
5. **Tested**: Ensure examples work

### Accessibility
1. **Document a11y Features**: Keyboard, screen readers
2. **Provide Guidelines**: How to use accessibly
3. **Include ARIA**: Document ARIA usage
4. **Test Instructions**: How to verify a11y

### Maintenance
1. **Keep Updated**: Update with code changes
2. **Version Docs**: Document per version
3. **Deprecation Warnings**: Clear migration paths
4. **Changelog**: Track all changes
5. **Feedback Loop**: Improve based on questions

## Tools & Resources

### Documentation Tools
- **Storybook**: Component development and docs
- **TypeDoc**: Generate API docs from TypeScript
- **Docusaurus**: Documentation website builder
- **VitePress**: Fast static site generator
- **Markdoc**: Markdown-based documentation

### Storybook Addons
- **@storybook/addon-a11y**: Accessibility testing
- **@storybook/addon-essentials**: Core addons
- **@storybook/addon-interactions**: Test interactions
- **@storybook/addon-links**: Link stories
- **storybook-dark-mode**: Dark mode toggle

### Writing Tools
- **Grammarly**: Grammar checking
- **Hemingway**: Readability improvement
- **Vale**: Prose linting
- **markdownlint**: Markdown linting

## When to Use This Skill

Activate this skill when you need to:
- Write or update README files
- Create Storybook stories
- Generate API documentation
- Write usage guides
- Create migration guides
- Document component props
- Write tutorials
- Create examples
- Set up documentation site
- Improve existing docs
- Write contributing guidelines

## Output Format

When creating documentation, provide:
1. **Complete Documentation**: README, stories, guides
2. **Code Examples**: Working, tested examples
3. **Screenshots**: Visual aids where helpful
4. **Links**: Cross-references to related docs
5. **Metadata**: Version, last updated, authors
6. **Next Steps**: What to read next

Always prioritize clarity, completeness, and accessibility in documentation.