Roster 📋

Roster is the atomic UI component library powering the MegaSquad ecosystem.

It is built with React 19, TypeScript, Tailwind CSS v4, and Vite, offering a set of high-quality, accessible, and theme-aware components.

🚀 Features

• Next.js App Router Ready: All components are automatically bundled with "use client" directives for seamless SSR integration without context crashes.
• Decoupled Theming: Bring your own brand. Roster ships structural CSS separately from its default design tokens, allowing you to easily override CSS variables or use the default MegaSquad theme.
• Atomic Design: Components organized by atoms, molecules, and organisms.
• TypeScript First: Fully typed for excellent developer experience (DX).
• Adaptive Dark Mode: Fully supports manual, class-based dark mode toggling (.dark) independent of OS preferences.
• Headless UI: Accessible interactive components powered by @headlessui/react.
• Tree-Shakeable: Import only what you need.

📦 Installation

npm install roster
# or
yarn add roster

Peer Dependencies

Roster relies on a few peer dependencies that must be installed in your host application:

"peerDependencies": {
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
  "tailwindcss": "^4.0.0"
}

💻 Usage

1. Import Styles

Roster splits its CSS into two parts to give you ultimate flexibility over your theme. You must import the CSS at the root of your application (e.g., in layout.tsx, main.tsx, or App.tsx).

// 1. Required: The structural Tailwind utility classes
import "roster/dist/roster.css";

// 2. Optional: The default MegaSquad color and theme tokens
// (Omit this file if you are defining your own --roster-* variables in your app's global CSS)
import "roster/dist/tokens.css";

### 2. Import Components

Now you can use the components anywhere in your app.

```tsx
import { Button, Spinner } from "roster";

function App() {
  return (
    <div className="p-4 flex flex-col gap-4">
      {/* Primary Button */}
      <Button colorScheme="primary" onClick={() => alert("Clicked!")}>
        Save Changes
      </Button>

      {/* Destructive Variant */}
      <Button colorScheme="destructive" variant="outline">
        Delete Account
      </Button>

      {/* Loading State */}
      <Button isLoading>Processing...</Button>

      {/* Standalone Spinner */}
      <Spinner size="lg" className="text-accent-500" />
    </div>
  );
}

🎨 Development

We use Storybook to develop and document components in isolation.

# Install dependencies
npm install

# Start Storybook
npm run storybook

This will open the component playground at http://localhost:6006.

🛠️ Building

To build the library for production (outputs to dist/):

npm run build

This generates:

• dist/roster.es.js (Main library ES Modules)
• dist/tokens.es.js (Token injection script)
• dist/roster.css (Compiled structural Tailwind styles)
• dist/tokens.css (Design token CSS variables)
• dist/index.d.ts (Type definitions)

📄 License

MIT © Blake Ball