@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

npm install @gsk-poc/untitled-ui-base

Peer Dependencies:

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):

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:

/** @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:

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

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="[email protected]" 
      />
      
      <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:

--color-brand-600       /* Primary brand color */
--color-text-primary    /* Primary text color */
--color-bg-primary      /* Primary background */
--color-border-primary  /* Border color */

Typography:

--font-family-body      /* Body font */
--font-size-text-md     /* Medium text size */
--line-height-text-md   /* Text line height */

Spacing:

--spacing-xs    /* 4px */
--spacing-md    /* 8px */
--spacing-xl    /* 16px */

Radius:

--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:

{
  "Brand": {
    "600": {
      "$type": "color",
      "$value": "rgba(46, 144, 250, 1)"
    }
  }
}

Then rebuild:

npm run build:tokens
npm run build

📖 Component API

Button

<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

<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

<Badge
  color="brand" | "gray" | "error" | "warning" | "success" | 
        "blue" | "indigo" | "purple" | "pink" | "orange"
  size="sm" | "md" | "lg"
>
  Badge Text
</Badge>

Avatar

<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:

<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:

.my-custom-theme {
  --color-brand-600: #your-brand-color;
  --font-family-body: 'Your Font', sans-serif;
  --radius-md: 0.75rem;
}

📦 Build & Development

Scripts

# 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:

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:

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:

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