@fabio.caffarello/react-design-system 1.5.2 → 1.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fabio.caffarello/react-design-system",
   "private": false,
-  "version": "1.5.2",
+  "version": "1.6.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/ui/atoms/Collapsible/Collapsible.stories.tsx

@@ -0,0 +1,124 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import Collapsible from "./Collapsible";
+import { Button, Text } from "../../atoms";
+
+const meta: Meta<typeof Collapsible> = {
+  title: "UI/Atoms/Collapsible",
+  component: Collapsible,
+  parameters: {
+    docs: {
+      description: {
+        component: "A generic, reusable collapsible component for any content. Supports both controlled and uncontrolled modes.",
+      },
+    },
+  },
+  argTypes: {
+    defaultOpen: {
+      control: "boolean",
+      description: "Initial open state (uncontrolled mode)",
+    },
+    disabled: {
+      control: "boolean",
+      description: "Whether the collapsible is disabled",
+    },
+    duration: {
+      control: "number",
+      description: "Animation duration in milliseconds",
+    },
+  },
+};
+
+export const Default: StoryObj<typeof Collapsible> = {
+  args: {
+    defaultOpen: true,
+    trigger: (
+      <div className="px-4 py-2 bg-gray-100 rounded-md">
+        <Text as="span" className="font-medium">Click to toggle</Text>
+      </div>
+    ),
+    children: (
+      <div className="px-4 py-2">
+        <Text>This is collapsible content that can be shown or hidden.</Text>
+      </div>
+    ),
+  },
+};
+
+export const DefaultClosed: StoryObj<typeof Collapsible> = {
+  args: {
+    defaultOpen: false,
+    trigger: (
+      <div className="px-4 py-2 bg-gray-100 rounded-md">
+        <Text as="span" className="font-medium">Click to expand</Text>
+      </div>
+    ),
+    children: (
+      <div className="px-4 py-2">
+        <Text>This content starts collapsed.</Text>
+      </div>
+    ),
+  },
+};
+
+export const Controlled: StoryObj<typeof Collapsible> = {
+  render: () => {
+    const [isOpen, setIsOpen] = useState(false);
+    return (
+      <div className="space-y-4">
+        <Button onClick={() => setIsOpen(!isOpen)}>
+          {isOpen ? "Close" : "Open"} (External Control)
+        </Button>
+        <Collapsible
+          open={isOpen}
+          onOpenChange={setIsOpen}
+          trigger={
+            <div className="px-4 py-2 bg-gray-100 rounded-md">
+              <Text as="span" className="font-medium">Controlled Collapsible</Text>
+            </div>
+          }
+        >
+          <div className="px-4 py-2">
+            <Text>This collapsible is controlled by external state.</Text>
+          </div>
+        </Collapsible>
+      </div>
+    );
+  },
+};
+
+export const WithStorage: StoryObj<typeof Collapsible> = {
+  args: {
+    defaultOpen: true,
+    storageKey: "storybook-collapsible-state",
+    trigger: (
+      <div className="px-4 py-2 bg-gray-100 rounded-md">
+        <Text as="span" className="font-medium">State persists in localStorage</Text>
+      </div>
+    ),
+    children: (
+      <div className="px-4 py-2">
+        <Text>Toggle this and refresh the page - the state will be preserved!</Text>
+      </div>
+    ),
+  },
+};
+
+export const Disabled: StoryObj<typeof Collapsible> = {
+  args: {
+    defaultOpen: true,
+    disabled: true,
+    trigger: (
+      <div className="px-4 py-2 bg-gray-100 rounded-md opacity-50">
+        <Text as="span" className="font-medium">Disabled (cannot toggle)</Text>
+      </div>
+    ),
+    children: (
+      <div className="px-4 py-2">
+        <Text>This content cannot be toggled.</Text>
+      </div>
+    ),
+  },
+};
+
+export default meta;

package/src/ui/atoms/Collapsible/Collapsible.test.tsx

@@ -0,0 +1,174 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import Collapsible from './Collapsible';
+
+describe('Collapsible', () => {
+  beforeEach(() => {
+    // Clear localStorage before each test
+    localStorage.clear();
+  });
+
+  afterEach(() => {
+    localStorage.clear();
+  });
+
+  it('renders trigger and children', () => {
+    render(
+      <Collapsible
+        trigger={<button>Toggle</button>}
+        defaultOpen={true}
+      >
+        <div>Content</div>
+      </Collapsible>
+    );
+
+    expect(screen.getByText('Toggle')).toBeInTheDocument();
+    expect(screen.getByText('Content')).toBeInTheDocument();
+  });
+
+  it('starts open when defaultOpen is true', () => {
+    render(
+      <Collapsible
+        trigger={<button>Toggle</button>}
+        defaultOpen={true}
+      >
+        <div>Content</div>
+      </Collapsible>
+    );
+
+    const content = screen.getByText('Content').parentElement;
+    expect(content).toHaveAttribute('aria-hidden', 'false');
+  });
+
+  it('starts closed when defaultOpen is false', () => {
+    render(
+      <Collapsible
+        trigger={<button>Toggle</button>}
+        defaultOpen={false}
+      >
+        <div>Content</div>
+      </Collapsible>
+    );
+
+    const content = screen.getByText('Content').parentElement;
+    expect(content).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('toggles content when trigger is clicked', async () => {
+    render(
+      <Collapsible
+        trigger={<button>Toggle</button>}
+        defaultOpen={true}
+      >
+        <div>Content</div>
+      </Collapsible>
+    );
+
+    const button = screen.getByText('Toggle');
+    const content = screen.getByText('Content').parentElement;
+
+    expect(content).toHaveAttribute('aria-hidden', 'false');
+
+    fireEvent.click(button);
+
+    await waitFor(() => {
+      expect(content).toHaveAttribute('aria-hidden', 'true');
+    });
+  });
+
+  it('calls onOpenChange when provided (controlled mode)', () => {
+    const handleOpenChange = vi.fn();
+    render(
+      <Collapsible
+        trigger={<button>Toggle</button>}
+        open={true}
+        onOpenChange={handleOpenChange}
+      >
+        <div>Content</div>
+      </Collapsible>
+    );
+
+    const button = screen.getByText('Toggle');
+    fireEvent.click(button);
+
+    expect(handleOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it('persists state in localStorage when storageKey is provided', async () => {
+    const storageKey = 'test-collapsible';
+    
+    const { rerender } = render(
+      <Collapsible
+        trigger={<button>Toggle</button>}
+        defaultOpen={true}
+        storageKey={storageKey}
+      >
+        <div>Content</div>
+      </Collapsible>
+    );
+
+    const button = screen.getByText('Toggle');
+    fireEvent.click(button);
+
+    await waitFor(() => {
+      expect(localStorage.getItem(storageKey)).toBe('false');
+    });
+
+    // Re-render and check state is restored
+    rerender(
+      <Collapsible
+        trigger={<button>Toggle</button>}
+        defaultOpen={true}
+        storageKey={storageKey}
+      >
+        <div>Content</div>
+      </Collapsible>
+    );
+
+    const content = screen.getByText('Content').parentElement;
+    expect(content).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('does not toggle when disabled', async () => {
+    render(
+      <Collapsible
+        trigger={<button>Toggle</button>}
+        defaultOpen={true}
+        disabled={true}
+      >
+        <div>Content</div>
+      </Collapsible>
+    );
+
+    const button = screen.getByText('Toggle');
+    const content = screen.getByText('Content').parentElement;
+
+    expect(button).toBeDisabled();
+    expect(content).toHaveAttribute('aria-hidden', 'false');
+
+    fireEvent.click(button);
+
+    // State should not change
+    await waitFor(() => {
+      expect(content).toHaveAttribute('aria-hidden', 'false');
+    }, { timeout: 100 });
+  });
+
+  it('has correct ARIA attributes', () => {
+    render(
+      <Collapsible
+        trigger={<button>Toggle</button>}
+        defaultOpen={true}
+      >
+        <div>Content</div>
+      </Collapsible>
+    );
+
+    const button = screen.getByText('Toggle');
+    const content = screen.getByText('Content').parentElement?.parentElement;
+
+    expect(button).toHaveAttribute('aria-expanded', 'true');
+    expect(button).toHaveAttribute('aria-controls');
+    expect(content).toHaveAttribute('id');
+  });
+});

package/src/ui/atoms/Collapsible/Collapsible.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import { useEffect, useRef, useState, type HTMLAttributes, type ReactNode } from 'react';
+import { useCollapsible, type UseCollapsibleOptions } from '../../hooks/useCollapsible';
+
+export interface CollapsibleProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  children: ReactNode;
+  trigger: ReactNode; // Content for the toggle button
+  defaultOpen?: boolean;
+  open?: boolean; // Controlled mode
+  onOpenChange?: (open: boolean) => void;
+  disabled?: boolean;
+  duration?: number; // Animation duration in ms
+  storageKey?: string; // For localStorage persistence
+}
+
+/**
+ * Collapsible Component
+ * 
+ * A generic, reusable collapsible component for any content.
+ * Supports both controlled and uncontrolled modes.
+ * Includes smooth animations and full ARIA support.
+ * 
+ * @example
+ * ```tsx
+ * <Collapsible
+ *   trigger={<button>Toggle</button>}
+ *   defaultOpen={true}
+ * >
+ *   <div>Collapsible content</div>
+ * </Collapsible>
+ * ```
+ */
+export default function Collapsible({
+  children,
+  trigger,
+  defaultOpen = true,
+  open,
+  onOpenChange,
+  disabled = false,
+  duration = 200,
+  storageKey,
+  className = '',
+  ...props
+}: CollapsibleProps) {
+  const { isOpen, toggle, setOpen } = useCollapsible({
+    defaultOpen,
+    open,
+    onOpenChange,
+    storageKey,
+  } as UseCollapsibleOptions);
+
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [height, setHeight] = useState<number | 'auto'>(isOpen ? 'auto' : 0);
+
+  // Update height when content changes or isOpen changes
+  useEffect(() => {
+    if (!contentRef.current) return;
+
+    if (isOpen) {
+      // Set to actual height for animation
+      setHeight(contentRef.current.scrollHeight);
+    } else {
+      // Set to 0 for collapse animation
+      setHeight(0);
+    }
+  }, [isOpen, children]);
+
+  // Handle resize to recalculate height
+  useEffect(() => {
+    if (!isOpen || !contentRef.current) return;
+
+    const resizeObserver = new ResizeObserver(() => {
+      if (contentRef.current && isOpen) {
+        setHeight(contentRef.current.scrollHeight);
+      }
+    });
+
+    resizeObserver.observe(contentRef.current);
+
+    return () => {
+      resizeObserver.disconnect();
+    };
+  }, [isOpen]);
+
+  const contentId = `collapsible-content-${Math.random().toString(36).substr(2, 9)}`;
+
+  return (
+    <div className={className} {...props}>
+      <button
+        type="button"
+        onClick={toggle}
+        disabled={disabled}
+        aria-expanded={isOpen}
+        aria-controls={contentId}
+        aria-disabled={disabled}
+        className="w-full text-left"
+      >
+        {trigger}
+      </button>
+      <div
+        id={contentId}
+        ref={contentRef}
+        style={{
+          height: typeof height === 'number' ? `${height}px` : height,
+          overflow: 'hidden',
+          transition: `height ${duration}ms ease-in-out`,
+        }}
+        aria-hidden={!isOpen}
+      >
+        <div>{children}</div>
+      </div>
+    </div>
+  );
+}

package/src/ui/atoms/SidebarItem/SidebarItem.stories.tsx

@@ -52,4 +52,48 @@ export const WithIcon: StoryObj<typeof SidebarItem> = {
   },
 };
 
+export const Nested: StoryObj<typeof SidebarItem> = {
+  args: {
+    href: "/epics",
+    children: "Epics",
+    isActive: false,
+    nested: true,
+    icon: (
+      <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+      </svg>
+    ),
+  },
+};
+
+export const NestedLevel2: StoryObj<typeof SidebarItem> = {
+  args: {
+    href: "/epics",
+    children: "Epics",
+    isActive: false,
+    nested: 2,
+    icon: (
+      <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+      </svg>
+    ),
+  },
+};
+
+export const DifferentIconSizes: StoryObj<typeof SidebarItem> = {
+  render: () => (
+    <div className="space-y-2 w-64">
+      <SidebarItem href="/test" iconSize="sm" icon={<span>📄</span>}>
+        Small Icon
+      </SidebarItem>
+      <SidebarItem href="/test" iconSize="md" icon={<span>📄</span>}>
+        Medium Icon (default)
+      </SidebarItem>
+      <SidebarItem href="/test" iconSize="lg" icon={<span>📄</span>}>
+        Large Icon
+      </SidebarItem>
+    </div>
+  ),
+};
+
 export default meta;

package/src/ui/atoms/SidebarItem/SidebarItem.test.tsx

@@ -22,4 +22,44 @@ describe("SidebarItem", () => {
     render(<SidebarItem href="/epics" icon={icon}>Epics</SidebarItem>);
     expect(screen.getByTestId("icon")).toBeInTheDocument();
   });
+
+  it("applies nested indent when nested is true", () => {
+    render(<SidebarItem href="/epics" nested={true}>Epics</SidebarItem>);
+    const link = screen.getByRole("link");
+    expect(link.className).toContain("pl-8");
+  });
+
+  it("applies nested indent for specific level", () => {
+    render(<SidebarItem href="/epics" nested={2}>Epics</SidebarItem>);
+    const link = screen.getByRole("link");
+    expect(link.className).toContain("pl-12");
+  });
+
+  it("uses default padding when not nested", () => {
+    render(<SidebarItem href="/epics">Epics</SidebarItem>);
+    const link = screen.getByRole("link");
+    expect(link.className).toContain("px-4");
+    expect(link.className).not.toContain("pl-8");
+  });
+
+  it("applies correct icon size classes", () => {
+    const icon = <span>Icon</span>;
+    const { rerender } = render(
+      <SidebarItem href="/test" icon={icon} iconSize="sm">Test</SidebarItem>
+    );
+    let iconSpan = screen.getByText("Icon").parentElement;
+    expect(iconSpan?.className).toContain("h-4 w-4");
+
+    rerender(
+      <SidebarItem href="/test" icon={icon} iconSize="md">Test</SidebarItem>
+    );
+    iconSpan = screen.getByText("Icon").parentElement;
+    expect(iconSpan?.className).toContain("h-5 w-5");
+
+    rerender(
+      <SidebarItem href="/test" icon={icon} iconSize="lg">Test</SidebarItem>
+    );
+    iconSpan = screen.getByText("Icon").parentElement;
+    expect(iconSpan?.className).toContain("h-6 w-6");
+  });
 });

package/src/ui/atoms/SidebarItem/SidebarItem.tsx

@@ -1,11 +1,14 @@
 'use client';
 
 import type { AnchorHTMLAttributes, ReactNode } from "react";
+import { SIDEBAR_TOKENS, getNestedIndentClass } from "../../tokens/sidebar";
 
 export interface SidebarItemProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
   href: string;
   isActive?: boolean;
   icon?: ReactNode;
+  nested?: boolean | number; // true = level 1, number = specific level
+  iconSize?: 'sm' | 'md' | 'lg'; // Default: 'md'
   children: ReactNode;
 }
 
@@ -26,25 +29,38 @@ export default function SidebarItem({
   href,
   isActive = false,
   icon,
+  nested = false,
+  iconSize = 'md',
   children,
   className = "",
   ...props
 }: SidebarItemProps) {
+  // Calculate nested level
+  const nestedLevel = typeof nested === 'number' ? nested : (nested ? 1 : 0);
+  
+  // Get indent class based on nested level
+  const indentClass = getNestedIndentClass(nestedLevel);
+
+  // Base classes using tokens
   const baseClasses = [
     "flex",
     "items-center",
-    "px-4",
-    "py-2",
-    "text-sm",
+    indentClass,
+    SIDEBAR_TOKENS.spacing.itemPaddingY,
+    SIDEBAR_TOKENS.text.sm,
     "font-medium",
     "rounded-md",
     "transition-colors",
     "hover:bg-gray-100",
   ];
 
+  // Active classes using tokens
   const activeClasses = isActive
-    ? "bg-indigo-50 text-indigo-700 border-r-2 border-indigo-600"
-    : "text-gray-700 hover:text-gray-900";
+    ? `${SIDEBAR_TOKENS.colors.active.bg} ${SIDEBAR_TOKENS.colors.active.text} border-r-2 ${SIDEBAR_TOKENS.colors.active.border}`
+    : `${SIDEBAR_TOKENS.colors.inactive.text} ${SIDEBAR_TOKENS.colors.inactive.hover}`;
+
+  // Icon size class from tokens
+  const iconSizeClass = SIDEBAR_TOKENS.icon[iconSize];
 
   const classes = [
     ...baseClasses,
@@ -54,7 +70,11 @@ export default function SidebarItem({
 
   return (
     <a href={href} className={classes} {...props}>
-      {icon && <span className="mr-3 flex-shrink-0">{icon}</span>}
+      {icon && (
+        <span className={`${iconSizeClass} ${SIDEBAR_TOKENS.spacing.iconMargin} shrink-0`}>
+          {icon}
+        </span>
+      )}
       <span>{children}</span>
     </a>
   );

package/src/ui/atoms/index.ts

@@ -28,3 +28,6 @@ export type { SkeletonProps } from "./Skeleton/Skeleton";
 
 export { default as SidebarItem } from "./SidebarItem/SidebarItem";
 export type { SidebarItemProps } from "./SidebarItem/SidebarItem";
+
+export { default as Collapsible } from "./Collapsible/Collapsible";
+export type { CollapsibleProps } from "./Collapsible/Collapsible";

package/src/ui/hooks/useCollapsible.ts

@@ -0,0 +1,83 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+
+export interface UseCollapsibleOptions {
+  defaultOpen?: boolean;
+  open?: boolean; // Controlled mode
+  onOpenChange?: (open: boolean) => void;
+  storageKey?: string; // For localStorage persistence
+}
+
+export interface UseCollapsibleReturn {
+  isOpen: boolean;
+  toggle: () => void;
+  setOpen: (open: boolean) => void;
+}
+
+/**
+ * useCollapsible Hook
+ * 
+ * Reusable hook for collapsible component logic.
+ * Supports both controlled and uncontrolled modes.
+ * Optional localStorage persistence.
+ * 
+ * @example
+ * ```tsx
+ * const { isOpen, toggle } = useCollapsible({
+ *   defaultOpen: true,
+ *   storageKey: 'my-collapsible-state'
+ * });
+ * ```
+ */
+export function useCollapsible({
+  defaultOpen = true,
+  open,
+  onOpenChange,
+  storageKey,
+}: UseCollapsibleOptions): UseCollapsibleReturn {
+  // Load initial state from localStorage if storageKey is provided
+  const getInitialState = useCallback((): boolean => {
+    if (storageKey && typeof window !== 'undefined') {
+      const stored = localStorage.getItem(storageKey);
+      if (stored !== null) {
+        return stored === 'true';
+      }
+    }
+    return defaultOpen;
+  }, [defaultOpen, storageKey]);
+
+  const [internalOpen, setInternalOpen] = useState<boolean>(getInitialState);
+
+  // Use controlled state if provided, otherwise use internal state
+  const isOpen = open !== undefined ? open : internalOpen;
+
+  // Persist to localStorage when state changes
+  useEffect(() => {
+    if (storageKey && typeof window !== 'undefined' && open === undefined) {
+      localStorage.setItem(storageKey, String(internalOpen));
+    }
+  }, [internalOpen, storageKey, open]);
+
+  const setOpen = useCallback(
+    (newOpen: boolean) => {
+      if (open === undefined) {
+        // Uncontrolled mode
+        setInternalOpen(newOpen);
+      }
+      // In controlled mode, parent handles state
+      onOpenChange?.(newOpen);
+    },
+    [open, onOpenChange]
+  );
+
+  const toggle = useCallback(() => {
+    setOpen(!isOpen);
+  }, [isOpen, setOpen]);
+
+  return {
+    isOpen,
+    toggle,
+    setOpen,
+  };
+}

package/src/ui/index.ts

@@ -1,3 +1,4 @@
 export * from "./atoms";
 export * from "./molecules";
 export * from "./organisms";
+export * from "./tokens/sidebar";

package/src/ui/molecules/SidebarGroup/SidebarGroup.stories.tsx

@@ -0,0 +1,173 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import SidebarGroup from "./SidebarGroup";
+import SidebarItem from "../../atoms/SidebarItem/SidebarItem";
+
+const meta: Meta<typeof SidebarGroup> = {
+  title: "UI/Molecules/SidebarGroup",
+  component: SidebarGroup,
+  parameters: {
+    docs: {
+      description: {
+        component: "A group container for sidebar items with optional title. Supports collapsible groups.",
+      },
+    },
+  },
+  argTypes: {
+    title: {
+      control: "text",
+      description: "Title text for the group",
+    },
+    collapsible: {
+      control: "boolean",
+      description: "Whether the group can be collapsed",
+    },
+    defaultCollapsed: {
+      control: "boolean",
+      description: "Initial collapsed state (uncontrolled mode)",
+    },
+  },
+};
+
+export const Default: StoryObj<typeof SidebarGroup> = {
+  args: {
+    title: "Agile",
+    children: (
+      <>
+        <SidebarItem href="/epics">Epics</SidebarItem>
+        <SidebarItem href="/stories">Stories</SidebarItem>
+        <SidebarItem href="/tasks">Tasks</SidebarItem>
+      </>
+    ),
+  },
+};
+
+export const WithoutTitle: StoryObj<typeof SidebarGroup> = {
+  args: {
+    children: (
+      <>
+        <SidebarItem href="/kanban">Kanban</SidebarItem>
+        <SidebarItem href="/sprints">Sprints</SidebarItem>
+      </>
+    ),
+  },
+};
+
+export const Collapsible: StoryObj<typeof SidebarGroup> = {
+  args: {
+    title: "Backlog",
+    collapsible: true,
+    defaultCollapsed: false,
+    children: (
+      <>
+        <SidebarItem href="/epics" nested={true}>Epics</SidebarItem>
+        <SidebarItem href="/stories" nested={true}>Stories</SidebarItem>
+        <SidebarItem href="/tasks" nested={true}>Tasks</SidebarItem>
+      </>
+    ),
+  },
+};
+
+export const CollapsibleDefaultCollapsed: StoryObj<typeof SidebarGroup> = {
+  args: {
+    title: "Backlog",
+    collapsible: true,
+    defaultCollapsed: true,
+    children: (
+      <>
+        <SidebarItem href="/epics" nested={true}>Epics</SidebarItem>
+        <SidebarItem href="/stories" nested={true}>Stories</SidebarItem>
+        <SidebarItem href="/tasks" nested={true}>Tasks</SidebarItem>
+      </>
+    ),
+  },
+};
+
+export const ControlledCollapsible: StoryObj<typeof SidebarGroup> = {
+  render: () => {
+    const [collapsed, setCollapsed] = useState(false);
+    return (
+      <div className="space-y-4">
+        <button
+          onClick={() => setCollapsed(!collapsed)}
+          className="px-4 py-2 bg-gray-100 rounded"
+        >
+          {collapsed ? "Expand" : "Collapse"} (External Control)
+        </button>
+        <SidebarGroup
+          title="Backlog"
+          collapsible={true}
+          collapsed={collapsed}
+          onCollapseChange={setCollapsed}
+        >
+          <SidebarItem href="/epics" nested={true}>Epics</SidebarItem>
+          <SidebarItem href="/stories" nested={true}>Stories</SidebarItem>
+          <SidebarItem href="/tasks" nested={true}>Tasks</SidebarItem>
+        </SidebarGroup>
+      </div>
+    );
+  },
+};
+
+export const WithNestedItems: StoryObj<typeof SidebarGroup> = {
+  args: {
+    title: "Backlog",
+    collapsible: true,
+    defaultCollapsed: false,
+    children: (
+      <>
+        <SidebarItem
+          href="/epics"
+          nested={true}
+          icon={
+            <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+            </svg>
+          }
+        >
+          Epics
+        </SidebarItem>
+        <SidebarItem
+          href="/stories"
+          nested={true}
+          icon={
+            <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+            </svg>
+          }
+        >
+          Stories
+        </SidebarItem>
+        <SidebarItem
+          href="/tasks"
+          nested={true}
+          icon={
+            <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4" />
+            </svg>
+          }
+        >
+          Tasks
+        </SidebarItem>
+      </>
+    ),
+  },
+};
+
+export const MultipleGroups: StoryObj<typeof SidebarGroup> = {
+  render: () => (
+    <div className="w-64 bg-white border-r border-gray-200 p-4 space-y-4">
+      <SidebarGroup title="Backlog" collapsible={true} defaultCollapsed={false}>
+        <SidebarItem href="/epics" nested={true}>Epics</SidebarItem>
+        <SidebarItem href="/stories" nested={true}>Stories</SidebarItem>
+        <SidebarItem href="/tasks" nested={true}>Tasks</SidebarItem>
+      </SidebarGroup>
+      <SidebarGroup>
+        <SidebarItem href="/kanban">Kanban</SidebarItem>
+        <SidebarItem href="/sprints">Sprints</SidebarItem>
+      </SidebarGroup>
+    </div>
+  ),
+};
+
+export default meta;

package/src/ui/molecules/SidebarGroup/SidebarGroup.test.tsx

@@ -0,0 +1,131 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import SidebarGroup from './SidebarGroup';
+import SidebarItem from '../../atoms/SidebarItem/SidebarItem';
+
+describe('SidebarGroup', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  afterEach(() => {
+    localStorage.clear();
+  });
+
+  it('renders title and children', () => {
+    render(
+      <SidebarGroup title="Test Group">
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    expect(screen.getByText('Test Group')).toBeInTheDocument();
+    expect(screen.getByText('Test Item')).toBeInTheDocument();
+  });
+
+  it('renders without title', () => {
+    render(
+      <SidebarGroup>
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    expect(screen.getByText('Test Item')).toBeInTheDocument();
+  });
+
+  it('collapses and expands when collapsible', async () => {
+    render(
+      <SidebarGroup title="Collapsible Group" collapsible={true} defaultCollapsed={false}>
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const title = screen.getByText('Collapsible Group').closest('button');
+    expect(title).toBeInTheDocument();
+    expect(screen.getByText('Test Item')).toBeInTheDocument();
+
+    fireEvent.click(title!);
+
+    await waitFor(() => {
+      const item = screen.queryByText('Test Item');
+      // Item should be hidden (aria-hidden="true")
+      expect(item?.parentElement?.parentElement).toHaveAttribute('aria-hidden', 'true');
+    });
+  });
+
+  it('starts collapsed when defaultCollapsed is true', () => {
+    render(
+      <SidebarGroup title="Collapsible Group" collapsible={true} defaultCollapsed={true}>
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const content = screen.getByText('Test Item').parentElement?.parentElement;
+    expect(content).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('calls onCollapseChange when provided (controlled mode)', () => {
+    const handleCollapseChange = vi.fn();
+    render(
+      <SidebarGroup
+        title="Controlled Group"
+        collapsible={true}
+        collapsed={false}
+        onCollapseChange={handleCollapseChange}
+      >
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const title = screen.getByText('Controlled Group').closest('button');
+    fireEvent.click(title!);
+
+    expect(handleCollapseChange).toHaveBeenCalledWith(true);
+  });
+
+  it('persists state in localStorage when storageKey is provided', async () => {
+    const storageKey = 'test-sidebar-group';
+    
+    render(
+      <SidebarGroup
+        title="Persistent Group"
+        collapsible={true}
+        defaultCollapsed={false}
+        storageKey={storageKey}
+      >
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const title = screen.getByText('Persistent Group').closest('button');
+    fireEvent.click(title!);
+
+    await waitFor(() => {
+      expect(localStorage.getItem(storageKey)).toBe('false');
+    });
+  });
+
+  it('shows chevron icon when collapsible and showChevron is true', () => {
+    render(
+      <SidebarGroup title="Group" collapsible={true} showChevron={true}>
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const title = screen.getByText('Group').closest('button');
+    const svg = title?.querySelector('svg');
+    expect(svg).toBeInTheDocument();
+  });
+
+  it('hides chevron icon when showChevron is false', () => {
+    render(
+      <SidebarGroup title="Group" collapsible={true} showChevron={false}>
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const title = screen.getByText('Group').closest('button');
+    const svg = title?.querySelector('svg');
+    expect(svg).not.toBeInTheDocument();
+  });
+});

package/src/ui/molecules/SidebarGroup/SidebarGroup.tsx

@@ -2,10 +2,18 @@
 
 import type { HTMLAttributes, ReactNode } from "react";
 import { Text } from "../../atoms";
+import Collapsible from "../../atoms/Collapsible/Collapsible";
+import { SIDEBAR_TOKENS } from "../../tokens/sidebar";
 
 export interface SidebarGroupProps extends HTMLAttributes<HTMLDivElement> {
   title?: string;
   children: ReactNode;
+  collapsible?: boolean;
+  defaultCollapsed?: boolean;
+  collapsed?: boolean; // Controlled mode
+  onCollapseChange?: (collapsed: boolean) => void;
+  storageKey?: string; // For localStorage persistence
+  showChevron?: boolean; // Default: true when collapsible
 }
 
 /**
@@ -25,28 +33,95 @@ export interface SidebarGroupProps extends HTMLAttributes<HTMLDivElement> {
 export default function SidebarGroup({
   title,
   children,
+  collapsible = false,
+  defaultCollapsed = false,
+  collapsed,
+  onCollapseChange,
+  storageKey,
+  showChevron = true,
   className = "",
   ...props
 }: SidebarGroupProps) {
-  const baseClasses = [
-    "space-y-1",
-  ];
+  const baseClasses = ["space-y-1"];
+  const classes = [...baseClasses, className].filter(Boolean).join(" ");
 
-  const classes = [
-    ...baseClasses,
-    className,
-  ].filter(Boolean).join(" ");
+  // Chevron icon component
+  const ChevronIcon = ({ isOpen }: { isOpen: boolean }) => (
+    <svg
+      className={`h-4 w-4 transition-transform duration-200 ${
+        isOpen ? 'rotate-90' : ''
+      }`}
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+    >
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        d="M9 5l7 7-7 7"
+      />
+    </svg>
+  );
+
+  // Title content with optional chevron
+  const titleContent = (
+    <>
+      <Text
+        as="h3"
+        className={`${SIDEBAR_TOKENS.text.xs} font-semibold ${SIDEBAR_TOKENS.colors.groupTitle} uppercase tracking-wider`}
+      >
+        {title}
+      </Text>
+      {collapsible && showChevron && (
+        <ChevronIcon isOpen={collapsed !== undefined ? !collapsed : !defaultCollapsed} />
+      )}
+    </>
+  );
+
+  // If collapsible and has title, use Collapsible component
+  if (collapsible && title) {
+    return (
+      <Collapsible
+        defaultOpen={!defaultCollapsed}
+        open={collapsed !== undefined ? !collapsed : undefined}
+        onOpenChange={(open) => onCollapseChange?.(!open)}
+        storageKey={storageKey}
+        trigger={
+          <div className={`${SIDEBAR_TOKENS.spacing.groupTitlePadding} flex items-center justify-between w-full`}>
+            <Text
+              as="h3"
+              className={`${SIDEBAR_TOKENS.text.xs} font-semibold ${SIDEBAR_TOKENS.colors.groupTitle} uppercase tracking-wider`}
+            >
+              {title}
+            </Text>
+            {showChevron && (
+              <ChevronIcon isOpen={collapsed !== undefined ? !collapsed : !defaultCollapsed} />
+            )}
+          </div>
+        }
+        className={classes}
+        {...props}
+      >
+        <div className="space-y-1">{children}</div>
+      </Collapsible>
+    );
+  }
 
+  // Non-collapsible group (default behavior)
   return (
     <div className={classes} {...props}>
       {title && (
-        <Text as="h3" className="px-4 py-2 text-xs font-semibold text-gray-500 uppercase tracking-wider">
-          {title}
-        </Text>
+        <div className={SIDEBAR_TOKENS.spacing.groupTitlePadding}>
+          <Text
+            as="h3"
+            className={`${SIDEBAR_TOKENS.text.xs} font-semibold ${SIDEBAR_TOKENS.colors.groupTitle} uppercase tracking-wider`}
+          >
+            {title}
+          </Text>
+        </div>
       )}
-      <div className="space-y-1">
-        {children}
-      </div>
+      <div className="space-y-1">{children}</div>
     </div>
   );
 }

package/src/ui/tokens/sidebar.ts

@@ -0,0 +1,60 @@
+/**
+ * Sidebar Design Tokens
+ * 
+ * Centralized tokens for sidebar components to ensure consistency
+ * and ease of maintenance. All spacing, sizing, and color values
+ * should reference these tokens.
+ */
+
+export const SIDEBAR_TOKENS = {
+  // Icon sizes
+  icon: {
+    sm: 'h-4 w-4',      // 16px
+    md: 'h-5 w-5',      // 20px (default)
+    lg: 'h-6 w-6',      // 24px
+  },
+  
+  // Text sizes
+  text: {
+    xs: 'text-xs',      // 12px (group titles)
+    sm: 'text-sm',      // 14px (items - default)
+    base: 'text-base',  // 16px
+  },
+  
+  // Spacing
+  spacing: {
+    itemPaddingX: 'px-4',           // 16px horizontal padding for items
+    itemPaddingY: 'py-2',          // 8px vertical padding for items
+    nestedIndent: 'pl-8',          // 32px for nested items (level 1)
+    nestedIndentLevel2: 'pl-12',   // 48px for nested items (level 2)
+    nestedIndentLevel3: 'pl-16',    // 64px for nested items (level 3)
+    groupTitlePadding: 'px-4 py-2', // Padding for group titles
+    iconMargin: 'mr-3',            // 12px margin between icon and text
+  },
+  
+  // Colors (using Tailwind classes)
+  colors: {
+    active: {
+      bg: 'bg-indigo-50',
+      text: 'text-indigo-700',
+      border: 'border-indigo-600',
+    },
+    inactive: {
+      text: 'text-gray-700',
+      hover: 'hover:bg-gray-100 hover:text-gray-900',
+    },
+    groupTitle: 'text-gray-500',
+  },
+} as const;
+
+/**
+ * Helper function to get nested indent class based on level
+ */
+export function getNestedIndentClass(level: number): string {
+  if (level <= 0) return SIDEBAR_TOKENS.spacing.itemPaddingX;
+  if (level === 1) return SIDEBAR_TOKENS.spacing.nestedIndent;
+  if (level === 2) return SIDEBAR_TOKENS.spacing.nestedIndentLevel2;
+  if (level === 3) return SIDEBAR_TOKENS.spacing.nestedIndentLevel3;
+  // For levels > 3, calculate dynamically: pl-{4 + level * 4}
+  return `pl-${4 + level * 4}`;
+}