ai-design-system 0.1.0

package/components/primitives/Separator/Separator.stories.tsx

@@ -0,0 +1,264 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Separator } from './Separator'
+
+/**
+ * Separator Primitive Stories
+ *
+ * The Separator component is a foundational primitive for visually dividing content.
+ * It extends shadcn/ui's Separator with design system-specific enhancements and maintains
+ * full accessibility compliance (WCAG 2.1 Level AA).
+ *
+ * ## Features
+ * - Horizontal and vertical orientations
+ * - Semantic HTML with proper ARIA attributes
+ * - Consistent styling across the application
+ * - Dark mode support
+ * - Decorative by default (not announced to screen readers)
+ *
+ * ## Accessibility
+ * - Uses semantic separator role
+ * - Decorative by default (aria-hidden)
+ * - Can be made non-decorative for semantic separators
+ * - Maintains proper color contrast ratios
+ *
+ * ## Usage Guidelines
+ *
+ * ### Do's
+ * - Use to visually separate content sections
+ * - Use horizontal separators for vertical content flow
+ * - Use vertical separators for horizontal content flow
+ * - Keep decorative for purely visual separators
+ *
+ * ### Don'ts
+ * - Don't use as a border replacement
+ * - Don't overuse - maintain visual hierarchy
+ * - Don't rely solely on separators to convey structure
+ */
+const meta = {
+  title: 'Primitives/Separator',
+  component: Separator,
+  tags: ['autodocs'],
+  argTypes: {
+    orientation: {
+      control: 'select',
+      options: ['horizontal', 'vertical'],
+      description: 'Orientation of the separator',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'horizontal' },
+      },
+    },
+    decorative: {
+      control: 'boolean',
+      description: 'Whether the separator is purely decorative',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'true' },
+      },
+    },
+  },
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'A visual separator component for dividing content, built on shadcn/ui foundation.',
+      },
+    },
+  },
+} satisfies Meta<typeof Separator>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Default (Horizontal)
+ *
+ * Basic horizontal separator.
+ */
+export const Default: Story = {
+  render: () => (
+    <div style={{ width: '300px' }}>
+      <Separator />
+    </div>
+  ),
+}
+
+/**
+ * Vertical
+ *
+ * Vertical separator for horizontal content layouts.
+ */
+export const Vertical: Story = {
+  render: () => (
+    <div style={{ display: 'flex', height: '100px', alignItems: 'center', gap: '16px' }}>
+      <div>Left Content</div>
+      <Separator orientation="vertical" />
+      <div>Right Content</div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Vertical separators are useful for dividing horizontally arranged content.',
+      },
+    },
+  },
+}
+
+/**
+ * In Content
+ *
+ * Separator used to divide text content sections.
+ */
+export const InContent: Story = {
+  render: () => (
+    <div style={{ maxWidth: '400px' }}>
+      <div style={{ marginBottom: '16px' }}>
+        <h3 style={{ fontSize: '16px', fontWeight: 600, marginBottom: '8px' }}>Section 1</h3>
+        <p style={{ fontSize: '14px', color: 'hsl(var(--muted-foreground))' }}>
+          This is the first section of content with some descriptive text.
+        </p>
+      </div>
+      <Separator />
+      <div style={{ marginTop: '16px' }}>
+        <h3 style={{ fontSize: '16px', fontWeight: 600, marginBottom: '8px' }}>Section 2</h3>
+        <p style={{ fontSize: '14px', color: 'hsl(var(--muted-foreground))' }}>
+          This is the second section of content with more descriptive text.
+        </p>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Separators help create visual hierarchy between content sections.',
+      },
+    },
+  },
+}
+
+/**
+ * In Navigation
+ *
+ * Separator used in navigation menus.
+ */
+export const InNavigation: Story = {
+  render: () => (
+    <div style={{ width: '200px', padding: '8px', border: '1px solid hsl(var(--border))', borderRadius: '8px' }}>
+      <div style={{ padding: '8px', fontSize: '14px' }}>Profile</div>
+      <div style={{ padding: '8px', fontSize: '14px' }}>Settings</div>
+      <Separator style={{ margin: '8px 0' }} />
+      <div style={{ padding: '8px', fontSize: '14px', color: 'hsl(var(--destructive))' }}>Logout</div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Separators can group related navigation items and separate destructive actions.',
+      },
+    },
+  },
+}
+
+/**
+ * Multiple Sections
+ *
+ * Multiple separators dividing several content sections.
+ */
+export const MultipleSections: Story = {
+  render: () => (
+    <div style={{ maxWidth: '400px' }}>
+      <div style={{ padding: '16px 0' }}>
+        <h3 style={{ fontSize: '16px', fontWeight: 600 }}>Header</h3>
+      </div>
+      <Separator />
+      <div style={{ padding: '16px 0' }}>
+        <p style={{ fontSize: '14px' }}>Main content area with important information.</p>
+      </div>
+      <Separator />
+      <div style={{ padding: '16px 0' }}>
+        <p style={{ fontSize: '12px', color: 'hsl(var(--muted-foreground))' }}>Footer information</p>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Multiple separators can create clear visual sections in a layout.',
+      },
+    },
+  },
+}
+
+/**
+ * With Flex Layout
+ *
+ * Separators in a flexbox layout with multiple items.
+ */
+export const WithFlexLayout: Story = {
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '16px' }}>
+      <div>Item 1</div>
+      <Separator orientation="vertical" style={{ height: '20px' }} />
+      <div>Item 2</div>
+      <Separator orientation="vertical" style={{ height: '20px' }} />
+      <div>Item 3</div>
+      <Separator orientation="vertical" style={{ height: '20px' }} />
+      <div>Item 4</div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Vertical separators work well in horizontal flex layouts.',
+      },
+    },
+  },
+}
+
+/**
+ * Dark Mode Preview
+ *
+ * Separators in dark mode to verify theming compatibility.
+ */
+export const DarkMode: Story = {
+  render: () => (
+    <div className="dark" style={{ padding: '24px', background: 'hsl(222.2 84% 4.9%)', borderRadius: '8px' }}>
+      <div style={{ maxWidth: '400px' }}>
+        <div style={{ marginBottom: '16px' }}>
+          <h3 style={{ fontSize: '16px', fontWeight: 600, marginBottom: '8px', color: 'hsl(var(--foreground))' }}>
+            Section 1
+          </h3>
+          <p style={{ fontSize: '14px', color: 'hsl(var(--muted-foreground))' }}>
+            This is the first section of content.
+          </p>
+        </div>
+        <Separator />
+        <div style={{ marginTop: '16px', marginBottom: '16px' }}>
+          <h3 style={{ fontSize: '16px', fontWeight: 600, marginBottom: '8px', color: 'hsl(var(--foreground))' }}>
+            Section 2
+          </h3>
+          <p style={{ fontSize: '14px', color: 'hsl(var(--muted-foreground))' }}>
+            This is the second section of content.
+          </p>
+        </div>
+        <Separator />
+        <div style={{ marginTop: '16px', display: 'flex', alignItems: 'center', gap: '16px' }}>
+          <div style={{ color: 'hsl(var(--foreground))' }}>Item 1</div>
+          <Separator orientation="vertical" style={{ height: '20px' }} />
+          <div style={{ color: 'hsl(var(--foreground))' }}>Item 2</div>
+          <Separator orientation="vertical" style={{ height: '20px' }} />
+          <div style={{ color: 'hsl(var(--foreground))' }}>Item 3</div>
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Separators automatically adapt to dark mode with appropriate contrast.',
+      },
+    },
+    backgrounds: { disable: true },
+  },
+}

package/components/primitives/Separator/Separator.tsx

@@ -0,0 +1,48 @@
+import * as React from "react"
+import { Separator as ShadcnSeparator } from "../../ui/separator"
+
+/**
+ * Separator Primitive
+ *
+ * A foundational separator component that wraps shadcn/ui Separator with design system
+ * enhancements. This primitive serves as the single source of truth for all visual
+ * separators across the application.
+ *
+ * @example
+ * ```tsx
+ * <Separator />
+ * <Separator orientation="vertical" />
+ * ```
+ *
+ * @see https://ui.shadcn.com/docs/components/separator - shadcn/ui Separator documentation
+ */
+
+/**
+ * Separator component props
+ * Extends the Radix UI Separator props
+ */
+export type SeparatorProps = React.ComponentPropsWithoutRef<typeof ShadcnSeparator>
+
+/**
+ * Separator component
+ *
+ * A visual separator component for dividing content, built on shadcn/ui foundation.
+ * Optimized with React.memo for performance in high-frequency rendering scenarios.
+ *
+ * Features:
+ * - Horizontal and vertical orientations
+ * - Semantic HTML with proper ARIA attributes
+ * - Consistent styling across the application
+ * - Dark mode support
+ * - Decorative by default (not announced to screen readers)
+ */
+export const Separator = React.memo(
+  React.forwardRef<
+    React.ElementRef<typeof ShadcnSeparator>,
+    SeparatorProps
+  >((props, ref) => {
+    return <ShadcnSeparator ref={ref} {...props} />
+  })
+)
+
+Separator.displayName = "Separator"

package/components/primitives/Separator/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Separator Primitive
+ *
+ * Central export point for the Separator primitive component and its related types.
+ */
+export { Separator } from './Separator'
+export type { SeparatorProps } from './Separator'

package/components/primitives/Sidebar/Sidebar.stories.tsx

@@ -0,0 +1,358 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  Sidebar,
+  SidebarProvider,
+  SidebarInset,
+  SidebarHeader,
+  SidebarContent,
+  SidebarFooter,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarTrigger,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+} from './Sidebar'
+
+/**
+ * Sidebar Primitive Stories
+ *
+ * The Sidebar component is a foundational primitive for application navigation.
+ * It extends shadcn/ui's Sidebar with design system-specific enhancements and maintains
+ * full accessibility compliance (WCAG 2.1 Level AA).
+ *
+ * ## Features
+ * - Collapsible sidebar with smooth animations
+ * - Responsive behavior (mobile/desktop)
+ * - Keyboard navigation support
+ * - Multiple variants (sidebar, floating, inset)
+ * - Dark mode support
+ *
+ * ## Accessibility
+ * - Proper ARIA attributes for navigation
+ * - Keyboard shortcuts (Cmd/Ctrl + B to toggle)
+ * - Focus management
+ * - Screen reader announcements
+ *
+ * ## Usage Guidelines
+ *
+ * ### Do's
+ * - Use for primary application navigation
+ * - Group related navigation items
+ * - Provide clear labels and icons
+ * - Use SidebarProvider to wrap the layout
+ *
+ * ### Don'ts
+ * - Don't use for secondary navigation
+ * - Don't nest multiple sidebars
+ * - Don't omit navigation labels
+ * - Don't use for temporary content (use Drawer instead)
+ */
+const meta = {
+  title: 'Primitives/Sidebar',
+  component: Sidebar,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: 'A collapsible sidebar component for application navigation, built on shadcn/ui foundation.',
+      },
+    },
+  },
+} satisfies Meta<typeof Sidebar>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Default sidebar
+ *
+ * Basic sidebar with navigation items.
+ */
+export const Default: Story = {
+  render: () => (
+    <SidebarProvider>
+      <div style={{ display: 'flex', minHeight: '400px', width: '100%' }}>
+        <Sidebar>
+          <SidebarHeader>
+            <div style={{ padding: '16px', fontWeight: 600 }}>My App</div>
+          </SidebarHeader>
+          <SidebarContent>
+            <SidebarMenu>
+              <SidebarMenuItem>
+                <SidebarMenuButton>Dashboard</SidebarMenuButton>
+              </SidebarMenuItem>
+              <SidebarMenuItem>
+                <SidebarMenuButton>Projects</SidebarMenuButton>
+              </SidebarMenuItem>
+              <SidebarMenuItem>
+                <SidebarMenuButton>Tasks</SidebarMenuButton>
+              </SidebarMenuItem>
+              <SidebarMenuItem>
+                <SidebarMenuButton>Settings</SidebarMenuButton>
+              </SidebarMenuItem>
+            </SidebarMenu>
+          </SidebarContent>
+          <SidebarFooter>
+            <div style={{ padding: '16px', fontSize: '12px', color: 'hsl(var(--muted-foreground))' }}>
+              © 2024 My App
+            </div>
+          </SidebarFooter>
+        </Sidebar>
+        <SidebarInset>
+          <header style={{ borderBottom: '1px solid hsl(var(--border))', padding: '16px', display: 'flex', alignItems: 'center', gap: '8px' }}>
+            <SidebarTrigger />
+            <h1 style={{ fontSize: '18px', fontWeight: 600 }}>Page Title</h1>
+          </header>
+          <main style={{ padding: '24px' }}>
+            <p>Main content area. Click the trigger button to toggle the sidebar.</p>
+          </main>
+        </SidebarInset>
+      </div>
+    </SidebarProvider>
+  ),
+}
+
+/**
+ * With Groups
+ *
+ * Sidebar with grouped navigation items.
+ */
+export const WithGroups: Story = {
+  render: () => (
+    <SidebarProvider>
+      <div style={{ display: 'flex', minHeight: '400px', width: '100%' }}>
+        <Sidebar>
+          <SidebarHeader>
+            <div style={{ padding: '16px', fontWeight: 600 }}>My App</div>
+          </SidebarHeader>
+          <SidebarContent>
+            <SidebarGroup>
+              <SidebarGroupLabel>Main</SidebarGroupLabel>
+              <SidebarGroupContent>
+                <SidebarMenu>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton>Dashboard</SidebarMenuButton>
+                  </SidebarMenuItem>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton>Analytics</SidebarMenuButton>
+                  </SidebarMenuItem>
+                </SidebarMenu>
+              </SidebarGroupContent>
+            </SidebarGroup>
+            <SidebarGroup>
+              <SidebarGroupLabel>Projects</SidebarGroupLabel>
+              <SidebarGroupContent>
+                <SidebarMenu>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton>All Projects</SidebarMenuButton>
+                  </SidebarMenuItem>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton>Favorites</SidebarMenuButton>
+                  </SidebarMenuItem>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton>Archived</SidebarMenuButton>
+                  </SidebarMenuItem>
+                </SidebarMenu>
+              </SidebarGroupContent>
+            </SidebarGroup>
+            <SidebarGroup>
+              <SidebarGroupLabel>Settings</SidebarGroupLabel>
+              <SidebarGroupContent>
+                <SidebarMenu>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton>Profile</SidebarMenuButton>
+                  </SidebarMenuItem>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton>Preferences</SidebarMenuButton>
+                  </SidebarMenuItem>
+                </SidebarMenu>
+              </SidebarGroupContent>
+            </SidebarGroup>
+          </SidebarContent>
+        </Sidebar>
+        <SidebarInset>
+          <header style={{ borderBottom: '1px solid hsl(var(--border))', padding: '16px', display: 'flex', alignItems: 'center', gap: '8px' }}>
+            <SidebarTrigger />
+            <h1 style={{ fontSize: '18px', fontWeight: 600 }}>Grouped Navigation</h1>
+          </header>
+          <main style={{ padding: '24px' }}>
+            <p>Sidebar with grouped navigation items for better organization.</p>
+          </main>
+        </SidebarInset>
+      </div>
+    </SidebarProvider>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use SidebarGroup to organize related navigation items.',
+      },
+    },
+  },
+}
+
+/**
+ * With Active State
+ *
+ * Sidebar showing active navigation item.
+ */
+export const WithActiveState: Story = {
+  render: () => (
+    <SidebarProvider>
+      <div style={{ display: 'flex', minHeight: '400px', width: '100%' }}>
+        <Sidebar>
+          <SidebarHeader>
+            <div style={{ padding: '16px', fontWeight: 600 }}>My App</div>
+          </SidebarHeader>
+          <SidebarContent>
+            <SidebarMenu>
+              <SidebarMenuItem>
+                <SidebarMenuButton isActive>Dashboard</SidebarMenuButton>
+              </SidebarMenuItem>
+              <SidebarMenuItem>
+                <SidebarMenuButton>Projects</SidebarMenuButton>
+              </SidebarMenuItem>
+              <SidebarMenuItem>
+                <SidebarMenuButton>Tasks</SidebarMenuButton>
+              </SidebarMenuItem>
+              <SidebarMenuItem>
+                <SidebarMenuButton>Settings</SidebarMenuButton>
+              </SidebarMenuItem>
+            </SidebarMenu>
+          </SidebarContent>
+        </Sidebar>
+        <SidebarInset>
+          <header style={{ borderBottom: '1px solid hsl(var(--border))', padding: '16px', display: 'flex', alignItems: 'center', gap: '8px' }}>
+            <SidebarTrigger />
+            <h1 style={{ fontSize: '18px', fontWeight: 600 }}>Dashboard</h1>
+          </header>
+          <main style={{ padding: '24px' }}>
+            <p>The Dashboard item is marked as active in the sidebar.</p>
+          </main>
+        </SidebarInset>
+      </div>
+    </SidebarProvider>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use isActive prop to highlight the current page in navigation.',
+      },
+    },
+  },
+}
+
+/**
+ * Collapsed by Default
+ *
+ * Sidebar that starts in collapsed state.
+ */
+export const CollapsedByDefault: Story = {
+  render: () => (
+    <SidebarProvider defaultOpen={false}>
+      <div style={{ display: 'flex', minHeight: '400px', width: '100%' }}>
+        <Sidebar collapsible="icon">
+          <SidebarHeader>
+            <div style={{ padding: '16px', fontWeight: 600 }}>App</div>
+          </SidebarHeader>
+          <SidebarContent>
+            <SidebarMenu>
+              <SidebarMenuItem>
+                <SidebarMenuButton tooltip="Dashboard">Dashboard</SidebarMenuButton>
+              </SidebarMenuItem>
+              <SidebarMenuItem>
+                <SidebarMenuButton tooltip="Projects">Projects</SidebarMenuButton>
+              </SidebarMenuItem>
+              <SidebarMenuItem>
+                <SidebarMenuButton tooltip="Tasks">Tasks</SidebarMenuButton>
+              </SidebarMenuItem>
+              <SidebarMenuItem>
+                <SidebarMenuButton tooltip="Settings">Settings</SidebarMenuButton>
+              </SidebarMenuItem>
+            </SidebarMenu>
+          </SidebarContent>
+        </Sidebar>
+        <SidebarInset>
+          <header style={{ borderBottom: '1px solid hsl(var(--border))', padding: '16px', display: 'flex', alignItems: 'center', gap: '8px' }}>
+            <SidebarTrigger />
+            <h1 style={{ fontSize: '18px', fontWeight: 600 }}>Collapsed Sidebar</h1>
+          </header>
+          <main style={{ padding: '24px' }}>
+            <p>Sidebar starts collapsed. Hover over items to see tooltips.</p>
+          </main>
+        </SidebarInset>
+      </div>
+    </SidebarProvider>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Set defaultOpen={false} to start with a collapsed sidebar.',
+      },
+    },
+  },
+}
+
+/**
+ * Dark Mode Preview
+ *
+ * Sidebar in dark mode to verify theming compatibility.
+ */
+export const DarkMode: Story = {
+  render: () => (
+    <div className="dark" style={{ background: 'hsl(222.2 84% 4.9%)' }}>
+      <SidebarProvider>
+        <div style={{ display: 'flex', minHeight: '400px', width: '100%' }}>
+          <Sidebar>
+            <SidebarHeader>
+              <div style={{ padding: '16px', fontWeight: 600 }}>My App</div>
+            </SidebarHeader>
+            <SidebarContent>
+              <SidebarGroup>
+                <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+                <SidebarGroupContent>
+                  <SidebarMenu>
+                    <SidebarMenuItem>
+                      <SidebarMenuButton isActive>Dashboard</SidebarMenuButton>
+                    </SidebarMenuItem>
+                    <SidebarMenuItem>
+                      <SidebarMenuButton>Projects</SidebarMenuButton>
+                    </SidebarMenuItem>
+                    <SidebarMenuItem>
+                      <SidebarMenuButton>Tasks</SidebarMenuButton>
+                    </SidebarMenuItem>
+                  </SidebarMenu>
+                </SidebarGroupContent>
+              </SidebarGroup>
+            </SidebarContent>
+            <SidebarFooter>
+              <div style={{ padding: '16px', fontSize: '12px', color: 'hsl(var(--muted-foreground))' }}>
+                © 2024 My App
+              </div>
+            </SidebarFooter>
+          </Sidebar>
+          <SidebarInset>
+            <header style={{ borderBottom: '1px solid hsl(var(--border))', padding: '16px', display: 'flex', alignItems: 'center', gap: '8px' }}>
+              <SidebarTrigger />
+              <h1 style={{ fontSize: '18px', fontWeight: 600, color: 'hsl(var(--foreground))' }}>Dark Mode</h1>
+            </header>
+            <main style={{ padding: '24px', color: 'hsl(var(--foreground))' }}>
+              <p>Sidebar automatically adapts to dark mode with appropriate contrast.</p>
+            </main>
+          </SidebarInset>
+        </div>
+      </SidebarProvider>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Sidebar automatically adapts to dark mode with appropriate contrast and visibility.',
+      },
+    },
+    backgrounds: { disable: true },
+  },
+}