npm package: @primathonos/orion
Description: OpenStore Orion - Ant Design themed component library
Author: OpenStore Team
Latest version: 0.4.2

# OpenStore Orion Design System

A comprehensive design system built on **Ant Design** with **OpenStore Orion theming**. Get all the power of Ant Design with automatic OpenStore branding and Tailwind CSS customization support.

## 🌟 Features

- **🎨 Figma-Accurate Theming**: Exact colors and specifications from OpenStore design
- **⚡ Full Ant Design Power**: Access to ALL Ant Design components and props
- **🎯 Zero Configuration**: Automatic theming with no setup required
- **🔧 Tailwind Overrides**: Customize with Tailwind CSS classes
- **♿ Accessibility**: WCAG 2.1 AA compliant (from Ant Design)
- **📱 Responsive**: Mobile-first design approach
- **🔄 TypeScript**: Full type safety from Ant Design
- **🚀 Production Ready**: Battle-tested components

## 📦 Installation

```bash
# Using bun (recommended)
bun add @openstore/orion

# Using npm
npm install @openstore/orion

# Using yarn
yarn add @openstore/orion
```

## 🚀 Quick Start

### Option A: Global Provider (Recommended)

```tsx
import { OrionProvider, Button, Card, Table, Select } from '@openstore/orion';

function App() {
  return (
    <OrionProvider>
      {/* All Ant Design components automatically get Orion theme */}
      <Card title="Product Management">
        <Select showSearch placeholder="Filter categories...">
          <Select.Option value="electronics">Electronics</Select.Option>
          <Select.Option value="clothing">Clothing</Select.Option>
        </Select>
        <Table 
          dataSource={products} 
          columns={columns}
          rowSelection={{ type: 'checkbox' }}
          pagination={{ pageSize: 10 }}
        />
        <Button type="primary">Add Product</Button>
      </Card>
    </OrionProvider>
  );
}
```

### Option B: Individual Components (Auto-themed)

```tsx
import { Button, Card, Input, Table } from '@openstore/orion';

function MyComponent() {
  return (
    <Card title="Bundle Settings">
      <Input placeholder="Bundle name" />
      <Table dataSource={data} columns={columns} />
      <Button type="primary">Create Bundle</Button>
    </Card>
  );
}
```

## 🎨 Design Tokens

### Colors (From Figma)
- **Primary**: `#1D4A88` (Orion Blue)
- **Primary Hover**: `#27599E`
- **Primary Active**: `#11386C`
- **Success**: `#34a853`
- **Error**: `#ea4335`
- **Warning**: `#fbbc04`

### Typography
- **Font Family**: Inter
- **Font Weight**: 500 (Medium)
- **Font Sizes**: 12px, 14px, 16px, 18px, 20px

### Spacing & Layout
- **Border Radius**: 8px (from Figma)
- **Button Heights**: 36px (small), 40px (medium), 44px (large)
- **Padding**: 10px 16px (from Figma)
- **Shadow**: `0px 1px 2px 0px rgba(16, 24, 40, 0.05)` (from Figma)

## 🧩 Components

### Button (Full Ant Design API)

```tsx
import { Button } from '@openstore/orion';

// All Ant Design Button props work
<Button type="primary">Primary</Button>
<Button type="default">Default</Button>
<Button type="dashed">Dashed</Button>
<Button type="text">Text</Button>
<Button type="link">Link</Button>

// All Ant Design features
<Button type="primary" icon={<PlusOutlined />}>With Icon</Button>
<Button type="primary" loading>Loading</Button>
<Button type="primary" danger>Danger</Button>
<Button type="primary" disabled>Disabled</Button>
<Button type="primary" block>Full Width</Button>
<Button type="primary" size="large">Large</Button>
<Button type="primary" shape="round">Round</Button>
<Button type="primary" ghost>Ghost</Button>

// With Tailwind overrides
<Button 
  type="primary" 
  className="shadow-lg transform hover:scale-105"
>
  Custom Styled
</Button>
```

### Table (Full Ant Design API)

```tsx
import { Table, Tag, Button } from '@openstore/orion';

// All Ant Design Table props work
<Table
  dataSource={products}
  columns={columns}
  rowSelection={{
    type: 'checkbox',
    onChange: (selectedRowKeys, selectedRows) => {
      console.log('Selected:', selectedRowKeys, selectedRows);
    },
  }}
  expandable={{
    expandedRowRender: (record) => (
      <div>Expanded content for {record.name}</div>
    ),
  }}
  pagination={{
    pageSize: 10,
    showSizeChanger: true,
    showQuickJumper: true,
  }}
  scroll={{ x: 1200, y: 600 }}
  sticky
  virtual
  loading={isLoading}
  bordered
  className="shadow-lg rounded-xl"
/>
```

### Select (Full Ant Design API)

```tsx
import { Select } from '@openstore/orion';

// All Ant Design Select props work
<Select
  showSearch                       // Searchable
  mode="multiple"                  // Multiple selection
  allowClear                       // Clear button
  placeholder="Search and select..."
  optionFilterProp="children"
  filterOption={(input, option) =>
    option?.children?.toLowerCase().includes(input.toLowerCase())
  }
  maxTagCount="responsive"
  className="shadow-lg"
>
  <Select.Option value="electronics">Electronics</Select.Option>
  <Select.Option value="clothing">Clothing</Select.Option>
</Select>
```

### Dropdown (Full Ant Design API)

```tsx
import { Dropdown, Button } from '@openstore/orion';

// All Ant Design Dropdown props work
<Dropdown
  menu={{
    items: [
      { key: 'edit', label: 'Edit', icon: <EditOutlined /> },
      { key: 'copy', label: 'Copy', icon: <CopyOutlined /> },
      { type: 'divider' },
      { key: 'delete', label: 'Delete', icon: <DeleteOutlined />, danger: true },
    ],
    onClick: ({ key }) => handleAction(key),
  }}
  trigger={['click']}
  placement="bottomLeft"
  arrow
>
  <Button>Actions</Button>
</Dropdown>
```

### FloatButton (Full Ant Design API)

```tsx
import { FloatButton } from '@openstore/orion';

// Single float button
<FloatButton 
  icon={<PlusOutlined />}
  type="primary"
  tooltip="Add Product"
  onClick={handleAdd}
/>

// Float button group
<FloatButton.Group 
  trigger="click" 
  icon={<MoreOutlined />}
>
  <FloatButton icon={<PlusOutlined />} tooltip="Add" />
  <FloatButton icon={<EditOutlined />} tooltip="Edit" />
  <FloatButton icon={<DeleteOutlined />} tooltip="Delete" />
</FloatButton.Group>

// Back to top button
<FloatButton.BackTop visibilityHeight={100} />
```

### Card (Full Ant Design API)

```tsx
import { Card, Button, Avatar } from '@openstore/orion';

// All Ant Design Card props work
<Card 
  title="Product Details"
  extra={<Button type="primary">Edit</Button>}
  actions={[
    <Button key="save">Save</Button>,
    <Button key="cancel">Cancel</Button>
  ]}
  cover={<img src="product.jpg" />}
  hoverable
  bordered={false}
  size="small"
>
  <Card.Meta 
    title="Product Name"
    description="Product description"
    avatar={<Avatar src="avatar.jpg" />}
  />
</Card>

// With Tailwind overrides
<Card 
  title="Custom Card"
  className="border-orion-200 shadow-xl hover:shadow-2xl transition-shadow"
>
  <p>Custom styled card</p>
</Card>
```

### All Ant Design Components Available

```tsx
import { 
  Input, 
  Form, 
  Modal, 
  Drawer, 
  Menu, 
  Tabs, 
  Badge, 
  Tag, 
  Tooltip, 
  Popover, 
  Space,
  Divider,
  Typography,
  Layout,
  Row,
  Col,
  Checkbox,
  Radio,
  Switch,
  DatePicker,
  Upload,
  Progress,
  Spin,
  Alert,
  message,
  notification,
  // ... and 30+ more components
} from '@openstore/orion';

// All components automatically get Orion theming
<Form>
  <Form.Item label="Name">
    <Input placeholder="Enter name" />
  </Form.Item>
  <Form.Item label="Category">
    <Select placeholder="Select category">
      <Select.Option value="electronics">Electronics</Select.Option>
      <Select.Option value="clothing">Clothing</Select.Option>
    </Select>
  </Form.Item>
</Form>
```

## 🎯 Customization

### Theme Overrides

```tsx
import { OrionProvider } from '@openstore/orion';

const customTheme = {
  token: {
    colorPrimary: '#custom-color', // Override primary color
    borderRadius: 12, // Override border radius
  }
};

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

### Tailwind Class Overrides

```tsx
import { Button, Card } from '@openstore/orion';

// Override any styling with Tailwind classes
<Button 
  type="primary"
  className="rounded-xl shadow-2xl transform hover:scale-110 transition-all duration-300"
>
  Custom Button
</Button>

<Card 
  title="Custom Card"
  className="border-2 border-orion-500 bg-gradient-to-r from-orion-50 to-blue-50"
>
  Gradient card background
</Card>
```

## 🔄 Migration Guide

### From Shopify Polaris

```tsx
// Before (Shopify Polaris)
import { AppProvider, Button, Card, TextField } from '@shopify/polaris';

<AppProvider>
  <Card title="Settings">
    <TextField label="Name" />
    <Button primary>Save</Button>
  </Card>
</AppProvider>

// After (OpenStore Orion)
import { OrionProvider, Button, Card, Input } from '@openstore/orion';

<OrionProvider>
  <Card title="Settings">
    <Input placeholder="Name" />
    <Button type="primary">Save</Button>
  </Card>
</OrionProvider>
```

### From Custom Components

```tsx
// Before (Custom components)
import { Button, Card } from './custom-components';

// After (OpenStore Orion)
import { Button, Card } from '@openstore/orion';
// Same usage, but now with Ant Design power + Orion theming
```

## 🎯 Benefits

### vs Building Custom Components
- **✅ Faster Development**: No need to build components from scratch
- **✅ Better Quality**: Battle-tested Ant Design components
- **✅ More Features**: Get all Ant Design capabilities
- **✅ Less Maintenance**: Ant Design handles updates and bug fixes

### vs Plain Ant Design
- **✅ Automatic Branding**: OpenStore colors and styling applied
- **✅ Design Consistency**: Figma specifications implemented
- **✅ Tailwind Integration**: Easy customization with utility classes
- **✅ Zero Configuration**: Works out of the box

### vs Shopify Polaris
- **✅ More Components**: 50+ components vs Polaris's limited set
- **✅ Better Customization**: Tailwind overrides + theme configuration
- **✅ OpenStore Branding**: Designed for OpenStore ecosystem
- **✅ Modern Architecture**: Latest React patterns and TypeScript

## 🏢 Enterprise Features

### Complete Admin Interface Support
- **📊 Data Tables**: Sorting, filtering, pagination, row selection
- **📝 Forms**: Validation, layouts, field types
- **💬 Feedback**: Modals, drawers, messages, notifications
- **🧭 Navigation**: Menus, breadcrumbs, tabs
- **🎨 Display**: Cards, badges, tags, avatars
- **⚡ Actions**: Buttons, dropdowns, float buttons

### Production Ready
- **🛡️ Battle Tested**: Used by millions via Ant Design
- **♿ Accessibility**: WCAG 2.1 AA compliant
- **📱 Mobile Ready**: Responsive design built-in
- **🌐 i18n Support**: Internationalization ready
- **🎭 Theming**: Complete design system

## 📚 Documentation

- **Component API**: All Ant Design documentation applies
- **Theming Guide**: See theme configuration options
- **Examples**: Interactive playground with live examples
- **Migration**: Step-by-step migration guides

## 🔗 Links

- [Ant Design Documentation](https://ant.design/components/overview/)
- [OpenStore Design Guidelines](https://design.openstore.com)
- [GitHub Repository](https://github.com/openstore/orion-design-system)
- [NPM Package](https://www.npmjs.com/package/@openstore/orion)

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

---

Built with ❤️ by the OpenStore team.