@open-ai-school/ai-ui-library 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open AI School
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+<div align="center">
+
+# 🎨 AI UI Library
+
+**The shared design system for [Open AI School](https://open-ai-school.vercel.app)**
+
+[![npm version](https://img.shields.io/npm/v/@open-ai-school/ai-ui-library?color=6366f1&label=npm)](https://www.npmjs.com/package/@open-ai-school/ai-ui-library)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Storybook](https://img.shields.io/badge/Storybook-FF4785?logo=storybook&logoColor=white)](https://ui.open-ai-school.vercel.app)
+
+A production-ready React component library built with TypeScript, Tailwind CSS, and Framer Motion. Designed as the single source of truth for UI across all Open AI School programs.
+
+[**Live Storybook →**](https://ui.open-ai-school.vercel.app) · [**npm →**](https://www.npmjs.com/package/@open-ai-school/ai-ui-library) · [**Open AI School →**](https://open-ai-school.vercel.app)
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🧩 **Composable components** — Button, Card, Badge, ThemeToggle, ScrollReveal, and more
+- 🎭 **Dark/light mode** — Built-in ThemeProvider with system preference detection
+- 🎬 **Smooth animations** — Framer Motion integration in every interactive component
+- 🎨 **Design tokens** — CSS custom properties for consistent theming
+- 📦 **Tree-shakeable** — ESM + CJS dual output via tsup
+- 🔒 **TypeScript strict** — Full type safety with exported interfaces
+- ♿ **Accessible** — Keyboard-navigable, ARIA-compliant
+- 📖 **Storybook** — Interactive component playground with docs
+
+## 📦 Installation
+
+```bash
+npm install @open-ai-school/ai-ui-library
+```
+
+**Peer dependencies** (you likely already have these):
+
+```bash
+npm install react react-dom next
+```
+
+## 🚀 Quick Start
+
+```tsx
+import { Button, Card, Badge, ThemeProvider, ThemeToggle } from "@open-ai-school/ai-ui-library";
+import "@open-ai-school/ai-ui-library/styles.css";
+
+export default function App() {
+  return (
+    <ThemeProvider>
+      <div className="p-8 space-y-6">
+        <ThemeToggle />
+
+        <Card variant="glass" hover>
+          <Badge variant="success">New</Badge>
+          <h2>Welcome to Open AI School</h2>
+          <Button variant="primary" size="lg">
+            Start Learning →
+          </Button>
+        </Card>
+      </div>
+    </ThemeProvider>
+  );
+}
+```
+
+## 🧩 Components
+
+### `<Button />`
+
+Animated button with multiple variants and sizes.
+
+| Prop      | Type                                                    | Default     | Description           |
+| --------- | ------------------------------------------------------- | ----------- | --------------------- |
+| `variant` | `"primary" \| "secondary" \| "ghost" \| "outline" \| "accent"` | `"primary"` | Visual style          |
+| `size`    | `"sm" \| "md" \| "lg"`                                 | `"md"`      | Size                  |
+| `loading` | `boolean`                                               | `false`     | Shows spinner         |
+
+### `<Card />`
+
+Container with glassmorphism and hover effects.
+
+| Prop      | Type                                                | Default     | Description            |
+| --------- | --------------------------------------------------- | ----------- | ---------------------- |
+| `variant` | `"default" \| "elevated" \| "glass" \| "outline"`  | `"default"` | Visual style           |
+| `hover`   | `boolean`                                           | `false`     | Enable hover animation |
+
+### `<Badge />`
+
+Status indicator / label.
+
+| Prop      | Type                                                        | Default     | Description              |
+| --------- | ----------------------------------------------------------- | ----------- | ------------------------ |
+| `variant` | `"default" \| "success" \| "warning" \| "error" \| "info"` | `"default"` | Semantic color           |
+| `size`    | `"sm" \| "md"`                                              | `"sm"`      | Size                     |
+| `color`   | `string`                                                    | —           | Custom hex color override|
+
+### `<ThemeProvider />` & `<ThemeToggle />`
+
+Dark/light mode with system preference detection and localStorage persistence.
+
+### `<ScrollReveal />`
+
+Intersection Observer–powered entrance animations.
+
+### `<FloatingParticles />`
+
+Ambient animated background particles.
+
+### `<CourseProgress />` & `<WelcomeBanner />`
+
+Education-specific components for progress tracking and personalized greetings.
+
+## 🎨 Design Tokens
+
+Import the CSS to get the full token system:
+
+```css
+@import "@open-ai-school/ai-ui-library/styles.css";
+```
+
+### Available tokens
+
+| Token                   | Light          | Dark           |
+| ----------------------- | -------------- | -------------- |
+| `--color-primary`       | `#6366f1`      | `#818cf8`      |
+| `--color-accent`        | `#f59e0b`      | `#fbbf24`      |
+| `--color-bg`            | `#f8fafc`      | `#0f172a`      |
+| `--color-bg-card`       | `#ffffff`      | `#1e293b`      |
+| `--color-text`          | `#0f172a`      | `#f1f5f9`      |
+| `--color-text-muted`    | `#64748b`      | `#94a3b8`      |
+| `--color-border`        | `#e2e8f0`      | `#334155`      |
+
+See [`src/theme/tokens.css`](./src/theme/tokens.css) for the complete set.
+
+## 🏗️ Architecture
+
+```
+ai-ui-library/
+├── src/
+│   ├── components/     # React components
+│   │   ├── Button.tsx
+│   │   ├── Card.tsx
+│   │   ├── Badge.tsx
+│   │   ├── ThemeProvider.tsx
+│   │   ├── ThemeToggle.tsx
+│   │   ├── ScrollReveal.tsx
+│   │   ├── FloatingParticles.tsx
+│   │   ├── CourseProgress.tsx
+│   │   └── WelcomeBanner.tsx
+│   ├── hooks/          # Custom hooks
+│   │   ├── useProgress.ts
+│   │   └── useGuestProfile.ts
+│   ├── theme/          # Design tokens
+│   │   └── tokens.css
+│   ├── utils/          # Shared utilities
+│   └── index.ts        # Public API (barrel export)
+├── .storybook/         # Storybook configuration
+├── tsup.config.ts      # Build configuration
+├── tsconfig.json       # TypeScript configuration
+└── package.json
+```
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start Storybook dev server
+npm run storybook
+
+# Build the library
+npm run build
+
+# Watch mode (rebuild on changes)
+npm run dev
+```
+
+## 🌐 Used By
+
+This library powers every repo in the [Open AI School](https://github.com/open-ai-school) org:
+
+| Repo | Description |
+|------|-------------|
+| [`platform`](https://github.com/open-ai-school/platform) | Main Next.js app shell |
+| [`ai-seeds`](https://github.com/open-ai-school/ai-seeds) | 🌱 Level 1: Absolute beginners |
+| `ai-sprouts` | 🌿 Level 2: Foundations (coming soon) |
+| `ai-branches` | 🌳 Level 3: Applied AI (coming soon) |
+| `ai-canopy` | 🏕️ Level 4: Advanced (coming soon) |
+| `ai-forest` | 🌲 Level 5: Expert (coming soon) |
+
+## 🤝 Contributing
+
+We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.
+
+1. Fork the repo
+2. Create your feature branch: `git checkout -b feat/amazing-component`
+3. Add your component in `src/components/`
+4. Add a Storybook story
+5. Run `npm run build` to verify
+6. Submit a PR
+
+## 📄 License
+
+MIT © [Open AI School](https://github.com/open-ai-school)

package/dist/index.d.mts

@@ -0,0 +1,94 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, ButtonHTMLAttributes } from 'react';
+
+type Theme = "light" | "dark" | "system";
+declare function ThemeProvider({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare const useTheme: () => {
+    theme: Theme;
+    resolvedTheme: "light" | "dark";
+    setTheme: (theme: Theme) => void;
+};
+
+declare function ThemeToggle(): react_jsx_runtime.JSX.Element;
+
+type Animation = "fade-up" | "fade-in" | "scale-in" | "slide-left" | "slide-right";
+interface ScrollRevealProps {
+    children: ReactNode;
+    animation?: Animation;
+    delay?: number;
+    className?: string;
+    stagger?: boolean;
+}
+declare function ScrollReveal({ children, animation, delay, className, stagger, }: ScrollRevealProps): react_jsx_runtime.JSX.Element;
+
+declare function FloatingParticles(): react_jsx_runtime.JSX.Element;
+
+declare function CourseProgress({ totalLessons, basePath, programSlug, }: {
+    totalLessons: number;
+    basePath: string;
+    programSlug?: string;
+}): react_jsx_runtime.JSX.Element | null;
+
+declare function WelcomeBanner({ basePath }: {
+    basePath: string;
+}): react_jsx_runtime.JSX.Element | null;
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: "primary" | "secondary" | "ghost" | "outline" | "accent";
+    size?: "sm" | "md" | "lg";
+    loading?: boolean;
+}
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface CardProps {
+    children: ReactNode;
+    variant?: "default" | "elevated" | "glass" | "outline";
+    hover?: boolean;
+    className?: string;
+    onClick?: () => void;
+}
+declare function Card({ children, variant, hover, className, onClick, }: CardProps): react_jsx_runtime.JSX.Element;
+
+interface BadgeProps {
+    children: ReactNode;
+    variant?: "default" | "success" | "warning" | "error" | "info";
+    size?: "sm" | "md";
+    color?: string;
+    className?: string;
+}
+declare function Badge({ children, variant, size, color, className, }: BadgeProps): react_jsx_runtime.JSX.Element;
+
+interface ProgramProgress {
+    completed: string[];
+    timestamps: Record<string, string>;
+}
+type ProgressData = Record<string, ProgramProgress>;
+declare function useProgress(programSlug?: string): {
+    completed: string[];
+    completedCount: number;
+    totalCompleted: number;
+    markComplete: (lessonKey: string) => void;
+    isCompleted: (lessonKey: string) => boolean;
+    getCompletedAt: (lessonKey: string) => string | null;
+    getProgram: (slug: string) => ProgramProgress;
+    allData: ProgressData;
+    reset: () => void;
+};
+
+interface GuestProfile {
+    name: string;
+    avatar: string;
+    joinedAt: string;
+}
+interface GuestProfileContextValue {
+    profile: GuestProfile | null;
+    saveProfile: (name: string) => void;
+    clearProfile: () => void;
+    isSignedIn: boolean;
+}
+declare function useGuestProfile(): GuestProfileContextValue;
+
+export { Badge, type BadgeProps, Button, type ButtonProps, Card, type CardProps, CourseProgress, FloatingParticles, ScrollReveal, ThemeProvider, ThemeToggle, WelcomeBanner, useGuestProfile, useProgress, useTheme };

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, ButtonHTMLAttributes } from 'react';
+
+type Theme = "light" | "dark" | "system";
+declare function ThemeProvider({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare const useTheme: () => {
+    theme: Theme;
+    resolvedTheme: "light" | "dark";
+    setTheme: (theme: Theme) => void;
+};
+
+declare function ThemeToggle(): react_jsx_runtime.JSX.Element;
+
+type Animation = "fade-up" | "fade-in" | "scale-in" | "slide-left" | "slide-right";
+interface ScrollRevealProps {
+    children: ReactNode;
+    animation?: Animation;
+    delay?: number;
+    className?: string;
+    stagger?: boolean;
+}
+declare function ScrollReveal({ children, animation, delay, className, stagger, }: ScrollRevealProps): react_jsx_runtime.JSX.Element;
+
+declare function FloatingParticles(): react_jsx_runtime.JSX.Element;
+
+declare function CourseProgress({ totalLessons, basePath, programSlug, }: {
+    totalLessons: number;
+    basePath: string;
+    programSlug?: string;
+}): react_jsx_runtime.JSX.Element | null;
+
+declare function WelcomeBanner({ basePath }: {
+    basePath: string;
+}): react_jsx_runtime.JSX.Element | null;
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: "primary" | "secondary" | "ghost" | "outline" | "accent";
+    size?: "sm" | "md" | "lg";
+    loading?: boolean;
+}
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface CardProps {
+    children: ReactNode;
+    variant?: "default" | "elevated" | "glass" | "outline";
+    hover?: boolean;
+    className?: string;
+    onClick?: () => void;
+}
+declare function Card({ children, variant, hover, className, onClick, }: CardProps): react_jsx_runtime.JSX.Element;
+
+interface BadgeProps {
+    children: ReactNode;
+    variant?: "default" | "success" | "warning" | "error" | "info";
+    size?: "sm" | "md";
+    color?: string;
+    className?: string;
+}
+declare function Badge({ children, variant, size, color, className, }: BadgeProps): react_jsx_runtime.JSX.Element;
+
+interface ProgramProgress {
+    completed: string[];
+    timestamps: Record<string, string>;
+}
+type ProgressData = Record<string, ProgramProgress>;
+declare function useProgress(programSlug?: string): {
+    completed: string[];
+    completedCount: number;
+    totalCompleted: number;
+    markComplete: (lessonKey: string) => void;
+    isCompleted: (lessonKey: string) => boolean;
+    getCompletedAt: (lessonKey: string) => string | null;
+    getProgram: (slug: string) => ProgramProgress;
+    allData: ProgressData;
+    reset: () => void;
+};
+
+interface GuestProfile {
+    name: string;
+    avatar: string;
+    joinedAt: string;
+}
+interface GuestProfileContextValue {
+    profile: GuestProfile | null;
+    saveProfile: (name: string) => void;
+    clearProfile: () => void;
+    isSignedIn: boolean;
+}
+declare function useGuestProfile(): GuestProfileContextValue;
+
+export { Badge, type BadgeProps, Button, type ButtonProps, Card, type CardProps, CourseProgress, FloatingParticles, ScrollReveal, ThemeProvider, ThemeToggle, WelcomeBanner, useGuestProfile, useProgress, useTheme };