npm package: @gsk_poc/untitled-ui-base
Description: GSK wrapper for Untitled UI React components with custom design tokens
Author: GSK
Latest version: 0.1.26

# @gsk-poc/untitled-ui-base

A production-ready React component library built on Untitled UI with complete design token integration. All styling is driven by customizable design tokens exported from Figma.

## 🎯 Features

- ✅ **100% Token-Driven** - All colors, spacing, typography controlled via design tokens
- ✅ **50+ Components** - Buttons, inputs, modals, tables, charts, and more
- ✅ **TypeScript Support** - Full type definitions for excellent IDE experience
- ✅ **Tailwind CSS v4** - Modern utility-first CSS framework
- ✅ **React Aria** - Accessible components out of the box
- ✅ **Storybook Documentation** - Interactive component examples
- ✅ **Dark Mode Ready** - Built-in dark mode support via tokens
- ✅ **Tree-Shakeable** - Import only what you need

## 📦 Installation

```bash
npm install @gsk-poc/untitled-ui-base
```

**Peer Dependencies:**
```bash
npm install react@^19.0.0 react-dom@^19.0.0
```

## 🚀 Quick Start

### 1. Import CSS (Required)

In your app entry point (`main.tsx` or `App.tsx`):

```typescript
import '@gsk-poc/untitled-ui-base/styles/tokens.css';
import '@gsk-poc/untitled-ui-base/styles/globals.css';
import '@gsk-poc/untitled-ui-base/styles/theme.css';
import '@gsk-poc/untitled-ui-base/styles/typography.css';
```

**⚠️ Import Order Matters!** Always import in this sequence.

### 2. Configure Tailwind (Required)

Create or update `tailwind.config.js`:

```javascript
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    // ⚠️ CRITICAL: Include the library
    "./node_modules/@gsk-poc/untitled-ui-base/dist/**/*.{js,mjs}",
  ],
}
```

### 3. Add Tailwind Plugin to Vite

Update `vite.config.ts`:

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss()  // Add this
  ],
})
```

### 4. Use Components

```tsx
import { Button, Input, Badge } from '@gsk-poc/untitled-ui-base';

function App() {
  return (
    <div>
      <Button color="primary" size="md">
        Click Me
      </Button>
      
      <Input 
        label="Email" 
        type="email" 
        placeholder="you@company.com" 
      />
      
      <Badge color="brand">New</Badge>
    </div>
  );
}
```

## 📚 Available Components

### Base Components
- **Button** - Primary, secondary, tertiary, link, and destructive variants
- **Input** - Text inputs with validation and icons
- **Select** - Dropdown select with search
- **Checkbox** - Checkbox with label
- **Radio** - Radio button groups
- **Toggle** - Switch toggle
- **Textarea** - Multi-line text input
- **Badge** - Status badges in multiple colors
- **Avatar** - User avatars with initials or images
- **Tooltip** - Contextual tooltips
- **Progress Bar** - Progress indicators
- **Slider** - Range slider
- **Tags** - Tag chips with close button

### Application Components
- **Table** - Data tables with sorting and pagination
- **Tabs** - Tabbed interfaces
- **Modal** - Dialog modals
- **Pagination** - Page navigation
- **Carousel** - Image/content carousel
- **Date Picker** - Calendar date selection
- **Loading Indicator** - Spinners and loading states
- **Empty State** - No data placeholders
- **File Upload** - Drag-and-drop file uploads

### Foundation Components
- **Featured Icon** - Decorative icons with backgrounds
- **Rating Stars** - Star rating display
- **Social Icons** - Social media icons

## 🎨 Design Tokens

All styling is controlled through design tokens. You can customize the entire theme by updating token values.

### Token Categories

**Colors:**
```css
--color-brand-600       /* Primary brand color */
--color-text-primary    /* Primary text color */
--color-bg-primary      /* Primary background */
--color-border-primary  /* Border color */
```

**Typography:**
```css
--font-family-body      /* Body font */
--font-size-text-md     /* Medium text size */
--line-height-text-md   /* Text line height */
```

**Spacing:**
```css
--spacing-xs    /* 4px */
--spacing-md    /* 8px */
--spacing-xl    /* 16px */
```

**Radius:**
```css
--radius-sm     /* 0.25rem */
--radius-md     /* 0.5rem */
--radius-lg     /* 0.625rem */
```

### Customizing Tokens

To customize the design system, update `tokens/design-tokens.dtcg.json` in your fork:

```json
{
  "Brand": {
    "600": {
      "$type": "color",
      "$value": "rgba(46, 144, 250, 1)"
    }
  }
}
```

Then rebuild:

```bash
npm run build:tokens
npm run build
```

## 📖 Component API

### Button

```tsx
<Button
  color="primary" | "secondary" | "tertiary" | "link-gray" | "link-color" | 
        "primary-destructive" | "secondary-destructive" | "tertiary-destructive"
  size="sm" | "md" | "lg" | "xl"
  isDisabled={boolean}
  isLoading={boolean}
  showTextWhileLoading={boolean}
  iconLeading={ReactNode}
  iconTrailing={ReactNode}
  onClick={() => void}
>
  Button Text
</Button>
```

### Input

```tsx
<Input
  label="Email"
  type="text" | "email" | "password" | "number" | "tel" | "url" | "search"
  placeholder="Enter text..."
  value={string}
  onChange={(e) => void}
  isDisabled={boolean}
  isRequired={boolean}
  isInvalid={boolean}
  errorMessage="Error text"
  helperText="Helper text"
  iconLeading={ReactNode}
  iconTrailing={ReactNode}
/>
```

### Badge

```tsx
<Badge
  color="brand" | "gray" | "error" | "warning" | "success" | 
        "blue" | "indigo" | "purple" | "pink" | "orange"
  size="sm" | "md" | "lg"
>
  Badge Text
</Badge>
```

### Avatar

```tsx
<Avatar
  text="AB"
  size="xs" | "sm" | "md" | "lg" | "xl" | "2xl"
  src="https://example.com/avatar.jpg"
/>
```

## 🎨 Theming

### Light & Dark Mode

Dark mode is supported through the `.dark-mode` class:

```tsx
<div className="dark-mode">
  {/* All components will use dark mode tokens */}
  <Button color="primary">Dark Mode Button</Button>
</div>
```

### Custom Themes

Create custom themes by overriding CSS custom properties:

```css
.my-custom-theme {
  --color-brand-600: #your-brand-color;
  --font-family-body: 'Your Font', sans-serif;
  --radius-md: 0.75rem;
}
```

## 📦 Build & Development

### Scripts

```bash
# Build components
npm run build

# Generate design tokens
npm run build:tokens

# Start Storybook
npm run storybook

# Build Storybook
npm run build-storybook

# Type check
npm run type-check

# Lint
npm run lint

# Format code
npm run prettier
```

### Project Structure

```
@gsk-poc/untitled-ui-base/
├── components/           # React components
│   ├── base/            # Base UI components
│   ├── application/     # Complex components
│   └── foundations/     # Icons, logos
├── styles/              # CSS files
│   ├── globals.css      # Tailwind entry
│   ├── theme.css        # Token mappings (generated)
│   ├── tokens.css       # Raw tokens (generated)
│   └── typography.css   # Typography
├── tokens/              # Design tokens source
├── src/                 # Entry points
├── dist/                # Build output
└── .storybook/          # Storybook config
```

## 🔧 Troubleshooting

### Components Render as Plain Text

**Cause:** Tailwind isn't generating utility classes.

**Solution:** Ensure `tailwind.config.js` includes the library in `content`:

```javascript
content: [
  "./src/**/*.{js,ts,jsx,tsx}",
  "./node_modules/@gsk-poc/untitled-ui-base/dist/**/*.{js,mjs}",
]
```

### CSS Not Loading

**Cause:** CSS files not imported or in wrong order.

**Solution:** Import in your entry file:

```typescript
import '@gsk-poc/untitled-ui-base/styles/tokens.css';
import '@gsk-poc/untitled-ui-base/styles/globals.css';
import '@gsk-poc/untitled-ui-base/styles/theme.css';
```

### TypeScript Errors

**Cause:** Missing type declarations.

**Solution:** Ensure you have `@types/react` installed:

```bash
npm install --save-dev @types/react @types/react-dom
```

## 🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details

## 🔗 Links

- **Storybook:** [View Component Documentation](#)
- **Repository:** [Azure DevOps](#)
- **Issues:** [Report Issues](#)

## 📞 Support

For questions or issues:
- Create an issue in the repository
- Contact the design system team
- Check the troubleshooting section above

## 🎯 Roadmap

- [ ] Additional chart components
- [ ] More form validation examples
- [ ] Accessibility improvements
- [ ] Performance optimizations
- [ ] More theme examples

---

**Built with ❤️ by the GSK Design System Team**