ai-design-system 0.1.0

package/README.md

@@ -0,0 +1,307 @@
+# UI Library - Design System
+
+The official design system and component library for Bizmatters, built with Next.js, React, Tailwind CSS, and shadcn/ui.
+
+## Getting Started
+
+### Initial Setup
+
+After cloning the repository, set up the git hooks for design system governance:
+
+```bash
+cd packages/ui-lib
+./scripts/setup-hooks.sh
+```
+
+This will install pre-commit hooks that enforce:
+- Layer import architecture validation
+- Storybook coverage validation
+
+### Development Server
+
+Run the development server:
+
+```bash
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to see the result.
+
+### Storybook
+
+Run Storybook for component development and documentation:
+
+```bash
+pnpm storybook
+```
+
+Open [http://localhost:6006](http://localhost:6006) to view the component library.
+
+## Design System Governance
+
+### Pre-Commit Hooks
+
+The design system enforces strict quality standards through automated pre-commit hooks:
+
+**Master Validation Script**
+- Runs all design system validations in a single command
+- Run manually: `bash scripts/run-all-validations.sh` or `pnpm run prebuild`
+
+**Layer Import Architecture**
+- Validates that components follow the layered architecture pattern
+- Ensures primitives don't import from patterns or features
+- Ensures patterns don't import from features
+- Run manually: `python3 scripts/validate-layer-imports.py`
+
+**Storybook Coverage**
+- Ensures every component has a corresponding `.stories.tsx` file
+- Validates story file naming conventions
+- Run manually: `node scripts/validate-storybook-coverage.js`
+
+**Adding New Validations**
+To add a new validation to the master script, edit `scripts/run-all-validations.sh`:
+1. Add a new section with clear header and description
+2. Run your validation script and capture exit code
+3. Add the exit code to the final results check
+4. The script provides clear guidance with comments for adding new validations
+
+**Bypassing Hooks (Not Recommended)**
+```bash
+git commit --no-verify
+```
+
+Only bypass hooks if you have a valid reason and plan to fix violations immediately.
+
+## Project Structure
+
+```
+packages/ui-lib/
+├── components/
+│   ├── primitives/      # Base components (buttons, inputs, etc.)
+│   ├── patterns/        # Composite components (cards, forms, etc.)
+│   └── features/        # Feature-specific components
+├── scripts/
+│   ├── hooks/          # Git hooks (tracked in version control)
+│   │   └── pre-commit  # Pre-commit validation hook
+│   ├── setup-hooks.sh  # Hook installation script
+│   ├── run-all-validations.sh  # Master validation script
+│   ├── validate-layer-imports.py
+│   └── validate-storybook-coverage.js
+├── styles/             # Global styles and themes
+└── tokens/             # Design tokens
+```
+
+## Layer Architecture
+
+The design system follows a strict three-layer architecture:
+
+1. **Primitives** - Base components with no dependencies on other layers
+   - Examples: Button, Input, Textarea, Badge
+   - Can only import from external libraries and utilities
+
+2. **Patterns** - Composite components built from primitives
+   - Examples: Card, Form, Dialog
+   - Can import from primitives and external libraries
+
+3. **Features** - Feature-specific components
+   - Examples: AIConversation, RefinementPanel
+   - Can import from primitives, patterns, and external libraries
+
+**Import Rules:**
+- Primitives → No internal imports
+- Patterns → Can import Primitives
+- Features → Can import Primitives + Patterns
+
+## Available Scripts
+
+```bash
+pnpm dev                  # Start development server
+pnpm build                # Build for production
+pnpm start                # Start production server
+pnpm lint                 # Run ESLint
+pnpm tokens:build         # Build design tokens
+pnpm tokens:watch         # Watch design tokens
+pnpm storybook            # Start Storybook dev server
+pnpm build-storybook      # Build Storybook for production
+```
+
+## Creating New Components
+
+### 1. Choose the Correct Layer
+
+Determine which layer your component belongs to:
+- **Primitive**: Standalone, reusable UI element
+- **Pattern**: Combination of primitives
+- **Feature**: Domain-specific component
+
+### 2. Create Component File
+
+Create your component following the established structure:
+
+```tsx
+// components/primitives/YourComponent/YourComponent.tsx
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const yourComponentVariants = cva(
+  "base-classes",
+  {
+    variants: {
+      variant: {
+        default: "variant-classes",
+        secondary: "variant-classes",
+      },
+      size: {
+        default: "size-classes",
+        sm: "size-classes",
+        lg: "size-classes",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+);
+
+export interface YourComponentProps
+  extends React.HTMLAttributes<HTMLElement>,
+    VariantProps<typeof yourComponentVariants> {
+  // Additional props
+}
+
+export function YourComponent({
+  className,
+  variant,
+  size,
+  ...props
+}: YourComponentProps) {
+  return (
+    <div
+      className={cn(yourComponentVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}
+```
+
+### 3. Create Index File
+
+```tsx
+// components/primitives/YourComponent/index.ts
+export { YourComponent } from "./YourComponent";
+export type { YourComponentProps } from "./YourComponent";
+```
+
+### 4. Create Storybook Story (REQUIRED)
+
+Every component must have a `.stories.tsx` file:
+
+```tsx
+// components/primitives/YourComponent/YourComponent.stories.tsx
+import type { Meta, StoryObj } from "@storybook/react";
+import { YourComponent } from "./YourComponent";
+
+const meta = {
+  title: "Primitives/YourComponent",
+  component: YourComponent,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+} satisfies Meta<typeof YourComponent>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    // default props
+  },
+};
+
+export const Variant: Story = {
+  args: {
+    variant: "secondary",
+  },
+};
+```
+
+### 5. Validate
+
+Run validation scripts to ensure compliance:
+
+```bash
+# Run all validations (recommended)
+bash scripts/run-all-validations.sh
+# or
+pnpm run prebuild
+
+# Run individual validations
+python3 scripts/validate-layer-imports.py          # Layer architecture
+node scripts/validate-storybook-coverage.js        # Storybook coverage
+```
+
+## Design Tokens
+
+The design system uses Style Dictionary for design tokens management:
+
+```bash
+# Build tokens once
+pnpm tokens:build
+
+# Watch for changes
+pnpm tokens:watch
+```
+
+Tokens are defined in the `tokens/` directory and compiled to CSS custom properties.
+
+## Technology Stack
+
+- **Framework**: Next.js 16 with App Router
+- **UI**: React 19
+- **Styling**: Tailwind CSS 4
+- **Component Variants**: Class Variance Authority (CVA)
+- **Component Foundation**: Radix UI primitives
+- **Documentation**: Storybook 10
+- **Type Safety**: TypeScript 5 (strict mode)
+- **Icons**: Lucide React
+- **Animation**: Motion (Framer Motion)
+
+## Accessibility
+
+All components must meet WCAG 2.1 Level AA standards:
+- Keyboard navigation support
+- Screen reader compatibility
+- Proper ARIA attributes
+- Focus management
+- Color contrast requirements
+
+## Theming
+
+The design system supports:
+- Light and dark modes
+- Design token-based theming
+- CSS custom properties
+- Responsive design across all breakpoints
+
+## Contributing
+
+1. Set up git hooks: `./scripts/setup-hooks.sh`
+2. Create components following the layer architecture
+3. Include Storybook stories for all components
+4. Ensure all validations pass before committing
+5. Document accessibility features and keyboard shortcuts
+
+## Learn More
+
+- [Next.js Documentation](https://nextjs.org/docs)
+- [Tailwind CSS](https://tailwindcss.com)
+- [Radix UI](https://www.radix-ui.com)
+- [shadcn/ui](https://ui.shadcn.com)
+- [Storybook](https://storybook.js.org)
+- [CVA](https://cva.style)
+
+## Support
+
+For questions or issues with the design system, contact the Design System Guardian or open an issue in the repository.

package/components/ai-elements/actions.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+import type { ComponentProps } from "react";
+
+export type ActionsProps = ComponentProps<"div">;
+
+export const Actions = ({ className, children, ...props }: ActionsProps) => (
+  <div className={cn("flex items-center gap-1", className)} {...props}>
+    {children}
+  </div>
+);
+
+export type ActionProps = ComponentProps<typeof Button> & {
+  tooltip?: string;
+  label?: string;
+};
+
+export const Action = ({
+  tooltip,
+  children,
+  label,
+  className,
+  variant = "ghost",
+  size = "sm",
+  ...props
+}: ActionProps) => {
+  const button = (
+    <Button
+      className={cn(
+        "relative size-9 p-1.5 text-muted-foreground hover:text-foreground",
+        className
+      )}
+      size={size}
+      type="button"
+      variant={variant}
+      {...props}
+    >
+      {children}
+      <span className="sr-only">{label || tooltip}</span>
+    </Button>
+  );
+
+  if (tooltip) {
+    return (
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>{button}</TooltipTrigger>
+          <TooltipContent>
+            <p>{tooltip}</p>
+          </TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    );
+  }
+
+  return button;
+};

package/components/ai-elements/artifact.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+import { type LucideIcon, XIcon } from "lucide-react";
+import type { ComponentProps, HTMLAttributes } from "react";
+
+export type ArtifactProps = HTMLAttributes<HTMLDivElement>;
+
+export const Artifact = ({ className, ...props }: ArtifactProps) => (
+  <div
+    className={cn(
+      "flex flex-col overflow-hidden rounded-lg border bg-background shadow-sm",
+      className
+    )}
+    {...props}
+  />
+);
+
+export type ArtifactHeaderProps = HTMLAttributes<HTMLDivElement>;
+
+export const ArtifactHeader = ({
+  className,
+  ...props
+}: ArtifactHeaderProps) => (
+  <div
+    className={cn(
+      "flex items-center justify-between border-b bg-muted/50 px-4 py-3",
+      className
+    )}
+    {...props}
+  />
+);
+
+export type ArtifactCloseProps = ComponentProps<typeof Button>;
+
+export const ArtifactClose = ({
+  className,
+  children,
+  size = "sm",
+  variant = "ghost",
+  ...props
+}: ArtifactCloseProps) => (
+  <Button
+    className={cn(
+      "size-8 p-0 text-muted-foreground hover:text-foreground",
+      className
+    )}
+    size={size}
+    type="button"
+    variant={variant}
+    {...props}
+  >
+    {children ?? <XIcon className="size-4" />}
+    <span className="sr-only">Close</span>
+  </Button>
+);
+
+export type ArtifactTitleProps = HTMLAttributes<HTMLParagraphElement>;
+
+export const ArtifactTitle = ({ className, ...props }: ArtifactTitleProps) => (
+  <p
+    className={cn("font-medium text-foreground text-sm", className)}
+    {...props}
+  />
+);
+
+export type ArtifactDescriptionProps = HTMLAttributes<HTMLParagraphElement>;
+
+export const ArtifactDescription = ({
+  className,
+  ...props
+}: ArtifactDescriptionProps) => (
+  <p className={cn("text-muted-foreground text-sm", className)} {...props} />
+);
+
+export type ArtifactActionsProps = HTMLAttributes<HTMLDivElement>;
+
+export const ArtifactActions = ({
+  className,
+  ...props
+}: ArtifactActionsProps) => (
+  <div className={cn("flex items-center gap-1", className)} {...props} />
+);
+
+export type ArtifactActionProps = ComponentProps<typeof Button> & {
+  tooltip?: string;
+  label?: string;
+  icon?: LucideIcon;
+};
+
+export const ArtifactAction = ({
+  tooltip,
+  label,
+  icon: Icon,
+  children,
+  className,
+  size = "sm",
+  variant = "ghost",
+  ...props
+}: ArtifactActionProps) => {
+  const button = (
+    <Button
+      className={cn(
+        "size-8 p-0 text-muted-foreground hover:text-foreground",
+        className
+      )}
+      size={size}
+      type="button"
+      variant={variant}
+      {...props}
+    >
+      {Icon ? <Icon className="size-4" /> : children}
+      <span className="sr-only">{label || tooltip}</span>
+    </Button>
+  );
+
+  if (tooltip) {
+    return (
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>{button}</TooltipTrigger>
+          <TooltipContent>
+            <p>{tooltip}</p>
+          </TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    );
+  }
+
+  return button;
+};
+
+export type ArtifactContentProps = HTMLAttributes<HTMLDivElement>;
+
+export const ArtifactContent = ({
+  className,
+  ...props
+}: ArtifactContentProps) => (
+  <div className={cn("flex-1 overflow-auto p-4", className)} {...props} />
+);