@umituz/web-design-system 2.7.2 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-design-system",
-  "version": "2.7.2",
+  "version": "2.8.0",
   "private": false,
   "description": "Web Design System - Atomic Design components (Atoms, Molecules, Organisms, Templates) for React applications",
   "main": "./src/index.ts",

package/src/domain/tokens/responsive-map.tokens.ts

@@ -0,0 +1,243 @@
+/**
+ * Responsive Design Tokens
+ * @description Centralized mapping of size variants to Tailwind spacing scale values
+ *
+ * Scale values align with Tailwind's default spacing scale:
+ * 3=12px, 4=16px, 5=20px, 6=24px, 8=32px, 10=40px, 12=48px, 16=64px, 20=80px
+ *
+ * All responsive calculations are centralized here - components should NOT
+ * define their own size styles or do any spacing calculations.
+ */
+
+import type { SizeVariant, Breakpoint } from '../types';
+
+/**
+ * Spacing scale values for padding, margin, and gap
+ * Format: Tailwind spacing unit numbers (as strings for easier concatenation)
+ */
+export type SpacingScale = '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '12' | '14' | '16' | '20' | '24';
+
+/**
+ * Responsive spacing mapping by size variant and breakpoint
+ */
+export const RESPONSIVE_SPACING: Record<
+  SizeVariant,
+  Partial<Record<Breakpoint, SpacingScale>>
+> = {
+  xs: {
+    xs: '2',
+    sm: '3',
+    md: '3',
+    lg: '4',
+    xl: '4',
+    '2xl': '5',
+  },
+  sm: {
+    xs: '3',
+    sm: '4',
+    md: '4',
+    lg: '5',
+    xl: '6',
+    '2xl': '8',
+  },
+  md: {
+    xs: '4',
+    sm: '5',
+    md: '5',
+    lg: '6',
+    xl: '8',
+    '2xl': '10',
+  },
+  lg: {
+    xs: '5',
+    sm: '6',
+    md: '6',
+    lg: '8',
+    xl: '10',
+    '2xl': '12',
+  },
+  xl: {
+    xs: '6',
+    sm: '8',
+    md: '8',
+    lg: '10',
+    xl: '12',
+    '2xl': '16',
+  },
+} as const;
+
+/**
+ * Icon size scale values (height/width)
+ */
+export const RESPONSIVE_ICON_SIZE: Record<
+  SizeVariant,
+  Partial<Record<Breakpoint, SpacingScale>>
+> = {
+  xs: {
+    xs: '3',
+    sm: '4',
+    md: '5',
+    lg: '5',
+    xl: '6',
+    '2xl': '7',
+  },
+  sm: {
+    xs: '4',
+    sm: '5',
+    md: '6',
+    lg: '6',
+    xl: '8',
+    '2xl': '8',
+  },
+  md: {
+    xs: '5',
+    sm: '6',
+    md: '7',
+    lg: '8',
+    xl: '9',
+    '2xl': '10',
+  },
+  lg: {
+    xs: '6',
+    sm: '7',
+    md: '8',
+    lg: '9',
+    xl: '10',
+    '2xl': '12',
+  },
+  xl: {
+    xs: '8',
+    sm: '9',
+    md: '10',
+    lg: '12',
+    xl: '14',
+    '2xl': '16',
+  },
+} as const;
+
+/**
+ * Container/icon wrapper size (for rounded containers that hold icons)
+ */
+export const RESPONSIVE_CONTAINER_SIZE: Record<
+  SizeVariant,
+  Partial<Record<Breakpoint, SpacingScale>>
+> = {
+  xs: {
+    xs: '6',
+    sm: '8',
+    md: '8',
+    lg: '10',
+    xl: '10',
+    '2xl': '12',
+  },
+  sm: {
+    xs: '8',
+    sm: '10',
+    md: '10',
+    lg: '12',
+    xl: '12',
+    '2xl': '14',
+  },
+  md: {
+    xs: '10',
+    sm: '12',
+    md: '12',
+    lg: '14',
+    xl: '14',
+    '2xl': '16',
+  },
+  lg: {
+    xs: '12',
+    sm: '14',
+    md: '14',
+    lg: '16',
+    xl: '16',
+    '2xl': '20',
+  },
+  xl: {
+    xs: '14',
+    sm: '16',
+    md: '16',
+    lg: '20',
+    xl: '20',
+    '2xl': '24',
+  },
+} as const;
+
+/**
+ * Text size scale (Tailwind text utilities)
+ */
+export const RESPONSIVE_TEXT_SIZE: Record<
+  SizeVariant,
+  Partial<Record<'mobile' | 'tablet', string>>
+> = {
+  xs: {
+    mobile: 'text-xs',
+    tablet: 'sm:text-xs',
+  },
+  sm: {
+    mobile: 'text-xs',
+    tablet: 'sm:text-sm',
+  },
+  md: {
+    mobile: 'text-sm',
+    tablet: 'sm:text-base',
+  },
+  lg: {
+    mobile: 'text-base',
+    tablet: 'sm:text-lg',
+  },
+  xl: {
+    mobile: 'text-lg',
+    tablet: 'sm:text-xl',
+  },
+} as const;
+
+/**
+ * Gap/Spacing between elements (space-y-*, space-x-*, gap-*)
+ */
+export const RESPONSIVE_GAP: Record<
+  SizeVariant,
+  Partial<Record<Breakpoint, SpacingScale>>
+> = {
+  xs: {
+    xs: '1',
+    sm: '2',
+    md: '2',
+    lg: '3',
+    xl: '3',
+    '2xl': '4',
+  },
+  sm: {
+    xs: '2',
+    sm: '3',
+    md: '3',
+    lg: '4',
+    xl: '4',
+    '2xl': '5',
+  },
+  md: {
+    xs: '3',
+    sm: '4',
+    md: '4',
+    lg: '5',
+    xl: '5',
+    '2xl': '6',
+  },
+  lg: {
+    xs: '4',
+    sm: '5',
+    md: '5',
+    lg: '6',
+    xl: '6',
+    '2xl': '8',
+  },
+  xl: {
+    xs: '5',
+    sm: '6',
+    md: '6',
+    lg: '8',
+    xl: '8',
+    '2xl': '10',
+  },
+} as const;

package/src/infrastructure/utils/index.ts

@@ -8,3 +8,13 @@ export {
   cn,
 } from './cn.util';
 export type { ClassValue } from './cn.util';
+
+export {
+  getSpacing,
+  getIconSize,
+  getContainerSize,
+  getTextSize,
+  getGap,
+  getSpaceY,
+  getResponsiveStyles,
+} from './responsive.utils';

package/src/infrastructure/utils/responsive.utils.ts

@@ -0,0 +1,166 @@
+/**
+ * Responsive Utility Functions
+ * @description Centralized functions for building responsive Tailwind classes
+ * All responsive class construction logic lives here - components should only call these functions
+ */
+
+import { cn } from './cn.util';
+import type { SizeVariant, Breakpoint } from '../../domain/types';
+import {
+  RESPONSIVE_SPACING,
+  RESPONSIVE_ICON_SIZE,
+  RESPONSIVE_CONTAINER_SIZE,
+  RESPONSIVE_TEXT_SIZE,
+  RESPONSIVE_GAP,
+} from '../../domain/tokens/responsive-map.tokens';
+
+/**
+ * Build responsive padding/margin/gap classes
+ * @param property - Tailwind spacing property ('p', 'm', 'px', 'py', 'gap', 'space-y', 'space-x')
+ * @param size - Size variant (sm, md, lg, xl)
+ * @returns Complete responsive class string
+ *
+ * @example
+ * getSpacing('p', 'md') // "p-4 sm:p-5 md:p-5 lg:p-6 xl:p-8 2xl:p-10"
+ */
+export function getSpacing(
+  property: 'p' | 'm' | 'px' | 'py' | 'pt' | 'pb' | 'pl' | 'pr' | 'gap' | 'space-y' | 'space-x',
+  size: SizeVariant
+): string {
+  const token = RESPONSIVE_SPACING[size];
+
+  // Start with base (xs/mobile) value
+  const classes: string[] = [`${property}-${token.xs}`];
+
+  // Add breakpoint-specific classes
+  const breakpoints: Breakpoint[] = ['sm', 'md', 'lg', 'xl', '2xl'];
+  breakpoints.forEach((bp) => {
+    if (token[bp] !== token.xs) {
+      classes.push(`${bp}:${property}-${token[bp]}`);
+    }
+  });
+
+  return classes.join(' ');
+}
+
+/**
+ * Build responsive icon size classes (height + width)
+ * @param size - Size variant
+ * @returns Combined height and width classes
+ *
+ * @example
+ * getIconSize('md') // "h-5 w-5 sm:h-6 sm:w-6 md:h-7 md:w-7 lg:h-8 lg:w-8 xl:h-9 xl:w-9 2xl:h-10 2xl:w-10"
+ */
+export function getIconSize(size: SizeVariant): string {
+  const token = RESPONSIVE_ICON_SIZE[size];
+  const classes: string[] = [`h-${token.xs}`, `w-${token.xs}`];
+
+  const breakpoints: Breakpoint[] = ['sm', 'md', 'lg', 'xl', '2xl'];
+  breakpoints.forEach((bp) => {
+    if (token[bp] !== token.xs) {
+      classes.push(`${bp}:h-${token[bp]}`, `${bp}:w-${token[bp]}`);
+    }
+  });
+
+  return classes.join(' ');
+}
+
+/**
+ * Build responsive container size classes (for icon wrappers)
+ * @param size - Size variant
+ * @returns Combined height, width, and flex center classes
+ *
+ * @example
+ * getContainerSize('md') // "w-10 h-10 sm:w-12 sm:h-12 md:w-12 md:h-12..."
+ */
+export function getContainerSize(size: SizeVariant): string {
+  const token = RESPONSIVE_CONTAINER_SIZE[size];
+  const classes: string[] = [`w-${token.xs}`, `h-${token.xs}`];
+
+  const breakpoints: Breakpoint[] = ['sm', 'md', 'lg', 'xl', '2xl'];
+  breakpoints.forEach((bp) => {
+    if (token[bp] !== token.xs) {
+      classes.push(`${bp}:w-${token[bp]}`, `${bp}:h-${token[bp]}`);
+    }
+  });
+
+  return classes.join(' ');
+}
+
+/**
+ * Get responsive text size classes
+ * @param size - Size variant
+ * @returns Text size class string
+ *
+ * @example
+ * getTextSize('md') // "text-sm sm:text-base"
+ */
+export function getTextSize(size: SizeVariant): string {
+  const token = RESPONSIVE_TEXT_SIZE[size];
+  return cn(token.mobile, token.tablet);
+}
+
+/**
+ * Build responsive gap/spacing classes for layout
+ * @param size - Size variant
+ * @returns Gap class string
+ *
+ * @example
+ * getGap('md') // "gap-3 sm:gap-4 md:gap-4 lg:gap-5 xl:gap-5 2xl:gap-6"
+ */
+export function getGap(size: SizeVariant): string {
+  return getSpacing('gap', size);
+}
+
+/**
+ * Build responsive space-y classes for vertical stacking
+ * @param size - Size variant
+ * @returns Space-y class string
+ *
+ * @example
+ * getSpaceY('md') // "space-y-3 sm:space-y-4 md:space-y-4 lg:space-y-5..."
+ */
+export function getSpaceY(size: SizeVariant): string {
+  return getSpacing('space-y', size);
+}
+
+/**
+ * Get complete responsive styles for common component patterns
+ * @param size - Size variant
+ * @param options - Which styles to include
+ * @returns Combined class string
+ *
+ * @example
+ * getResponsiveStyles('md', { padding: true, gap: true })
+ * // "p-4 sm:p-5 md:p-5 lg:p-6 xl:p-8 2xl:p-10 gap-3 sm:gap-4..."
+ */
+export function getResponsiveStyles(
+  size: SizeVariant,
+  options: {
+    padding?: boolean;
+    gap?: boolean;
+    iconSize?: boolean;
+    textSize?: boolean;
+    containerSize?: boolean;
+  } = {}
+): string {
+  const classes: string[] = [];
+
+  if (options.padding) {
+    classes.push(getSpacing('p', size));
+  }
+  if (options.gap) {
+    classes.push(getGap(size));
+  }
+  if (options.iconSize) {
+    classes.push(getIconSize(size));
+  }
+  if (options.textSize) {
+    classes.push(getTextSize(size));
+  }
+  if (options.containerSize) {
+    classes.push(getContainerSize(size));
+  }
+
+  return classes.join(' ');
+}

package/src/presentation/molecules/FormField.tsx

@@ -1,10 +1,10 @@
 /**
  * FormField Component (Molecule)
- * @description Label + Input combination
+ * @description Label + Input combination (Responsive)
  */
 
 import { forwardRef } from 'react';
-import { cn } from '../../infrastructure/utils';
+import { cn, getSpaceY } from '../../infrastructure/utils';
 import type { BaseProps } from '../../domain/types';
 import { Input } from '../atoms/Input';
 import { Text } from '../atoms/Text';
@@ -16,20 +16,21 @@ export interface FormFieldProps extends BaseProps {
   required?: boolean;
   id?: string;
   inputProps?: React.ComponentProps<typeof Input>;
+  fullWidth?: boolean; // Enable responsive full width
 }
 
 export const FormField = forwardRef<HTMLInputElement, FormFieldProps>(
-  ({ label, error, helperText, required, id, className, inputProps, ...props }, ref) => {
+  ({ label, error, helperText, required, id, className, inputProps, fullWidth = true, ...props }, ref) => {
     const fieldId = id || inputProps?.id || inputProps?.name;
     const errorId = error ? `${fieldId}-error` : undefined;
     const helperId = helperText ? `${fieldId}-helper` : undefined;
 
     return (
-      <div className={cn('space-y-1.5', className)} {...props}>
+      <div className={cn(getSpaceY('sm'), fullWidth && 'w-full', className)} {...props}>
         {label && (
-          <label htmlFor={fieldId} className="text-sm font-medium">
+          <label htmlFor={fieldId} className="text-sm font-medium block">
             {label}
-            {required && <span className="text-destructive ml-1">*</span>}
+            {required && <span className="text-destructive ml-1" aria-label="required">*</span>}
           </label>
         )}
 

package/src/presentation/molecules/Select.tsx

@@ -21,7 +21,7 @@ const SelectTrigger = React.forwardRef<
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
-      'flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
+      'flex h-9 sm:h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
       className
     )}
     {...props}

package/src/presentation/organisms/EmptyState.tsx

@@ -1,10 +1,10 @@
 /**
  * EmptyState Component (Organism)
- * @description Component for displaying empty states with optional actions
+ * @description Component for displaying empty states with optional actions (Responsive)
  */
 
 import { forwardRef } from 'react';
-import { cn } from '../../infrastructure/utils';
+import { cn, getSpacing, getGap } from '../../infrastructure/utils';
 import type { BaseProps, SizeVariant } from '../../domain/types';
 
 export interface EmptyStateProps extends BaseProps {
@@ -16,36 +16,9 @@ export interface EmptyStateProps extends BaseProps {
     onClick: () => void;
   };
   size?: Extract<SizeVariant, 'sm' | 'md' | 'lg' | 'xl'>;
+  centered?: boolean;
 }
 
-const sizeStyles = {
-  sm: 'p-6 gap-3',
-  md: 'p-8 gap-4',
-  lg: 'p-12 gap-5',
-  xl: 'p-16 gap-6',
-};
-
-const iconSizeStyles = {
-  sm: 'h-8 w-8',
-  md: 'h-12 w-12',
-  lg: 'h-16 w-16',
-  xl: 'h-20 w-20',
-};
-
-const titleSizeStyles = {
-  sm: 'text-sm',
-  md: 'text-base',
-  lg: 'text-lg',
-  xl: 'text-xl',
-};
-
-const descriptionSizeStyles = {
-  sm: 'text-xs',
-  md: 'text-sm',
-  lg: 'text-base',
-  xl: 'text-lg',
-};
-
 export const EmptyState = forwardRef<HTMLDivElement, EmptyStateProps>(
   (
     {
@@ -64,17 +37,18 @@ export const EmptyState = forwardRef<HTMLDivElement, EmptyStateProps>(
         ref={ref}
         className={cn(
           'flex flex-col items-center justify-center text-center',
-          sizeStyles[size],
+          getSpacing('p', size),
+          getGap(size === 'xl' ? 'lg' : size),
           className
         )}
         {...props}
       >
         {Icon && (
-          <Icon className={cn(iconSizeStyles[size], 'text-muted-foreground/50 mx-auto mb-2')} />
+          <Icon className={cn(size === 'sm' ? 'h-8 w-8 sm:h-10 sm:w-10' : size === 'md' ? 'h-12 w-12 sm:h-14 sm:w-14' : size === 'lg' ? 'h-16 w-16 sm:h-20 sm:w-20' : 'h-20 w-20 sm:h-24 sm:w-24', 'text-muted-foreground/50 mx-auto mb-2')} />
         )}
-        <h3 className={cn('font-semibold text-foreground', titleSizeStyles[size])}>{title}</h3>
+        <h3 className={cn('font-semibold text-foreground', size === 'sm' ? 'text-sm sm:text-base' : size === 'md' ? 'text-base sm:text-lg' : size === 'lg' ? 'text-lg sm:text-xl' : 'text-xl sm:text-2xl')}>{title}</h3>
         {description && (
-          <p className={cn('text-muted-foreground max-w-md', descriptionSizeStyles[size])}>
+          <p className={cn('text-muted-foreground max-w-md', size === 'sm' ? 'text-xs sm:text-sm' : size === 'md' ? 'text-sm sm:text-base' : size === 'lg' ? 'text-base sm:text-lg' : 'text-lg sm:text-xl')}>
             {description}
           </p>
         )}

package/src/presentation/organisms/Grid.tsx

@@ -0,0 +1,129 @@
+/**
+ * Grid Component (Organism)
+ * @description Responsive grid system with configurable columns
+ */
+
+import { cn } from '../../infrastructure/utils';
+import type { BaseProps } from '../../domain/types';
+import type { Breakpoint } from '../../domain/types/breakpoint.types';
+
+export interface GridProps extends BaseProps {
+  children: React.ReactNode;
+  cols?: {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    '2xl'?: number;
+  };
+  gap?: number | string;
+  className?: string;
+}
+
+/**
+ * Responsive grid system that adjusts columns based on breakpoint
+ * @param cols - Number of columns per breakpoint
+ * @param gap - Gap between items (spacing unit or custom value)
+ * @param children - Grid items
+ *
+ * @example
+ * ```tsx
+ * // Auto responsive: 1 col mobile, 2 tablet, 3 desktop
+ * <Grid cols={{ xs: 1, sm: 2, lg: 3 }}>
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ * </Grid>
+ *
+ * // Fixed 4 columns
+ * <Grid cols={{ lg: 4 }}>
+ *   {items.map(item => <Card key={item.id}>{item}</Card>)}
+ * </Grid>
+ * ```
+ */
+export const Grid = ({ children, cols = {}, gap = 4, className }: GridProps) => {
+  const {
+    xs = 1,
+    sm = xs,
+    md = sm,
+    lg = md,
+    xl = lg,
+    '2xl': xl2 = xl
+  } = cols;
+
+  const gridCols = cn(
+    'grid',
+    `grid-cols-${xs}`, // xs always applies (mobile-first)
+    sm !== xs && `sm:grid-cols-${sm}`,
+    md !== sm && `md:grid-cols-${md}`,
+    lg !== md && `lg:grid-cols-${lg}`,
+    xl !== lg && `xl:grid-cols-${xl}`,
+    xl2 !== xl && `2xl:grid-cols-${xl2}`
+  );
+
+  const gapClass = typeof gap === 'number' ? `gap-${gap}` : gap;
+
+  return (
+    <div className={cn(gridCols, gapClass, className)}>
+      {children}
+    </div>
+  );
+};
+
+Grid.displayName = 'Grid';
+
+/**
+ * Grid Item component for custom column spans
+ */
+export interface GridItemProps extends BaseProps {
+  children: React.ReactNode;
+  span?: {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    '2xl'?: number;
+  };
+  className?: string;
+}
+
+/**
+ * Grid item with custom column span per breakpoint
+ * @param span - Number of columns to span (1-12)
+ *
+ * @example
+ * ```tsx
+ * <Grid cols={{ lg: 4 }}>
+ *   <GridItem span={{ lg: 2 }}>Spans 2 columns</GridItem>
+ *   <GridItem>Regular 1 column</GridItem>
+ * </Grid>
+ * ```
+ */
+export const GridItem = ({ children, span = {}, className }: GridItemProps) => {
+  const {
+    xs = 1,
+    sm = xs,
+    md = sm,
+    lg = md,
+    xl = lg,
+    '2xl': xl2 = xl
+  } = span;
+
+  const colSpan = cn(
+    'col-span-1',
+    `sm:col-span-${sm}`,
+    `md:col-span-${md}`,
+    `lg:col-span-${lg}`,
+    `xl:col-span-${xl}`,
+    `2xl:col-span-${xl2}`
+  );
+
+  return (
+    <div className={cn(colSpan, className)}>
+      {children}
+    </div>
+  );
+};
+
+GridItem.displayName = 'GridItem';

package/src/presentation/organisms/LoadingState.tsx

@@ -1,10 +1,10 @@
 /**
  * LoadingState Component (Organism)
- * @description Component for displaying loading states
+ * @description Component for displaying loading states (Responsive)
  */
 
 import { forwardRef } from 'react';
-import { cn } from '../../infrastructure/utils';
+import { cn, getSpacing, getGap } from '../../infrastructure/utils';
 import { Spinner } from '../atoms/Spinner';
 import type { BaseProps, SizeVariant } from '../../domain/types';
 
@@ -12,26 +12,9 @@ export interface LoadingStateProps extends BaseProps {
   message?: string;
   size?: Extract<SizeVariant, 'sm' | 'md' | 'lg'>;
   variant?: 'spinner' | 'skeleton' | 'dots';
+  centered?: boolean;
 }
 
-const sizeStyles = {
-  sm: 'gap-3',
-  md: 'gap-4',
-  lg: 'gap-5',
-};
-
-const spinnerSizeStyles = {
-  sm: 'sm' as const,
-  md: 'md' as const,
-  lg: 'lg' as const,
-};
-
-const messageSizeStyles = {
-  sm: 'text-xs',
-  md: 'text-sm',
-  lg: 'text-base',
-};
-
 export const LoadingState = forwardRef<HTMLDivElement, LoadingStateProps>(
   (
     {
@@ -39,30 +22,34 @@ export const LoadingState = forwardRef<HTMLDivElement, LoadingStateProps>(
       message,
       size = 'md',
       variant = 'spinner',
+      centered = true,
       ...props
     },
     ref
   ) => {
+    const spinnerSize: 'sm' | 'md' | 'lg' = size;
     return (
       <div
         ref={ref}
         className={cn(
-          'flex flex-col items-center justify-center p-8',
-          sizeStyles[size],
+          'flex flex-col items-center justify-center',
+          getGap(size),
+          getSpacing('p', size),
+          centered && 'min-h-[200px] sm:min-h-[300px]',
           className
         )}
         {...props}
       >
-        {variant === 'spinner' && <Spinner size={spinnerSizeStyles[size]} />}
+        {variant === 'spinner' && <Spinner size={spinnerSize} />}
         {variant === 'dots' && (
-          <div className="flex gap-1">
+          <div className="flex gap-1 sm:gap-2">
             {[0, 1, 2].map((i) => (
               <div
                 key={i}
                 className={cn(
                   'w-2 h-2 bg-primary rounded-full animate-bounce',
-                  size === 'sm' && 'w-1.5 h-1.5',
-                  size === 'lg' && 'w-3 h-3'
+                  'w-1.5 h-1.5 sm:w-2 sm:h-2',
+                  'lg:w-2.5 h-2.5'
                 )}
                 style={{ animationDelay: `${i * 0.15}s` }}
               />
@@ -70,14 +57,14 @@ export const LoadingState = forwardRef<HTMLDivElement, LoadingStateProps>(
           </div>
         )}
         {variant === 'skeleton' && (
-          <div className="w-full space-y-3">
-            <div className="h-4 bg-muted animate-pulse rounded" style={{ width: '40%' }} />
-            <div className="h-3 bg-muted animate-pulse rounded" style={{ width: '70%' }} />
-            <div className="h-3 bg-muted animate-pulse rounded" style={{ width: '60%' }} />
+          <div className="w-full space-y-2 sm:space-y-3">
+            <div className="h-3 sm:h-4 bg-muted animate-pulse rounded w-2/3 sm:w-1/2" />
+            <div className="h-2.5 sm:h-3 bg-muted animate-pulse rounded w-full" />
+            <div className="h-2.5 sm:h-3 bg-muted animate-pulse rounded w-3/4" />
           </div>
         )}
         {message && variant !== 'skeleton' && (
-          <p className={cn('text-muted-foreground mt-2', messageSizeStyles[size])}>{message}</p>
+          <p className={cn('text-muted-foreground mt-2 sm:mt-3', size === 'sm' ? 'text-xs sm:text-sm' : size === 'md' ? 'text-sm sm:text-base' : 'text-base sm:text-lg', 'text-center max-w-md')}>{message}</p>
         )}
       </div>
     );

package/src/presentation/organisms/MetricCard.tsx

@@ -1,10 +1,10 @@
 /**
  * MetricCard Component (Organism)
- * @description Card component for displaying metrics and statistics with trend indicators
+ * @description Card component for displaying metrics and statistics with trend indicators (Responsive)
  */
 
 import { forwardRef } from 'react';
-import { cn } from '../../infrastructure/utils';
+import { cn, getSpacing, getIconSize, getTextSize, getGap } from '../../infrastructure/utils';
 import { Card, CardContent } from './Card';
 import type { BaseProps, ColorVariant, SizeVariant } from '../../domain/types';
 
@@ -21,32 +21,9 @@ export interface MetricCardProps extends BaseProps {
   variant?: ColorVariant;
   trendValueFormatter?: (value: number) => string;
   onClick?: () => void;
+  responsiveLayout?: boolean; // Enable responsive layout changes
 }
 
-const sizeStyles = {
-  sm: 'p-3',
-  md: 'p-4',
-  lg: 'p-5',
-};
-
-const valueSizeStyles = {
-  sm: 'text-lg',
-  md: 'text-2xl',
-  lg: 'text-3xl',
-};
-
-const iconSizeStyles = {
-  sm: 'h-4 w-4',
-  md: 'h-8 w-8',
-  lg: 'h-10 w-10',
-};
-
-const labelSizeStyles = {
-  sm: 'text-xs',
-  md: 'text-sm',
-  lg: 'text-base',
-};
-
 const trendColors: Record<ColorVariant, { positive: string; negative: string; bg: string }> = {
   primary: { positive: 'text-primary', negative: 'text-destructive', bg: 'bg-primary' },
   secondary: { positive: 'text-secondary', negative: 'text-destructive', bg: 'bg-secondary' },
@@ -68,6 +45,7 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(
       variant = 'primary',
       trendValueFormatter = (v) => `${v > 0 ? '+' : ''}${v}%`,
       onClick,
+      responsiveLayout = true,
       ...props
     },
     ref
@@ -87,34 +65,48 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(
         onClick={onClick}
         {...props}
       >
-        <CardContent className={cn(sizeStyles[size])}>
-          <div className="flex items-center justify-between">
-            <div className="flex-1">
-              <p className={cn('text-muted-foreground font-medium', labelSizeStyles[size])}>{title}</p>
-              <p className={cn('font-bold text-foreground', valueSizeStyles[size])}>
+        <CardContent className={getSpacing('p', size)}>
+          <div className={cn(
+            'flex items-center justify-between',
+            getGap('md'),
+            responsiveLayout && 'flex-col sm:flex-row'
+          )}>
+            <div className={cn(
+              'flex-1',
+              responsiveLayout && 'text-center sm:text-left w-full sm:w-auto'
+            )}>
+              <p className={cn('text-muted-foreground font-medium', getTextSize(size))}>{title}</p>
+              <p className={cn('font-bold text-foreground mt-1', size === 'sm' ? 'text-lg sm:text-xl' : size === 'md' ? 'text-2xl' : 'text-3xl sm:text-4xl')}>
                 {typeof value === 'number' ? value.toLocaleString() : value}
               </p>
               {trend && (
-                <div className="flex items-center gap-1 mt-1">
+                <div className={cn(
+                  'flex items-center gap-1 mt-1',
+                  responsiveLayout ? 'justify-center sm:justify-start' : ''
+                )}>
                   <span
                     className={cn(
-                      'text-xs font-medium',
+                      'text-xs sm:text-sm font-medium',
                       isPositive ? colors.positive : colors.negative
                     )}
                   >
                     {TrendIcon}
                   </span>
-                  <p className={cn('text-xs', isPositive ? colors.positive : colors.negative)}>
+                  <p className={cn('text-xs sm:text-sm', isPositive ? colors.positive : colors.negative)}>
                     {trendValueFormatter(trend.value)}
                   </p>
                   {trend.label && (
-                    <p className="text-xs text-muted-foreground ml-1">{trend.label}</p>
+                    <p className="text-xs text-muted-foreground ml-1 hidden sm:inline">{trend.label}</p>
                   )}
                 </div>
               )}
             </div>
             {Icon && (
-              <Icon className={cn(iconSizeStyles[size], iconColor, 'flex-shrink-0')} />
+              <div className={cn(
+                responsiveLayout ? 'sm:self-auto' : ''
+              )}>
+                <Icon className={cn(getIconSize(size), iconColor, 'flex-shrink-0')} />
+              </div>
             )}
           </div>
         </CardContent>

package/src/presentation/organisms/QuickActionCard.tsx

@@ -1,10 +1,10 @@
 /**
  * QuickActionCard Component (Organism)
- * @description Card component for quick navigation actions with icon
+ * @description Card component for quick navigation actions with icon (Responsive)
  */
 
 import { forwardRef } from 'react';
-import { cn } from '../../infrastructure/utils';
+import { cn, getSpacing, getIconSize, getContainerSize, getTextSize, getGap } from '../../infrastructure/utils';
 import type { BaseProps, SizeVariant } from '../../domain/types';
 
 export interface QuickActionCardProps extends BaseProps {
@@ -16,32 +16,9 @@ export interface QuickActionCardProps extends BaseProps {
   href?: string;
   size?: Extract<SizeVariant, 'sm' | 'md' | 'lg'>;
   target?: '_blank' | '_self' | '_parent' | '_top';
+  responsiveLayout?: boolean; // Enable responsive layout changes
 }
 
-const sizeStyles = {
-  sm: 'p-3 gap-2',
-  md: 'p-4 gap-3',
-  lg: 'p-5 gap-4',
-};
-
-const iconSizeStyles = {
-  sm: 'w-8 h-8',
-  md: 'w-10 h-10',
-  lg: 'w-12 h-12',
-};
-
-const iconInnerSizeStyles = {
-  sm: 'h-4 w-4',
-  md: 'h-5 w-5',
-  lg: 'h-6 w-6',
-};
-
-const labelSizeStyles = {
-  sm: 'text-xs',
-  md: 'text-sm',
-  lg: 'text-base',
-};
-
 export const QuickActionCard = forwardRef<HTMLAnchorElement | HTMLDivElement, QuickActionCardProps>(
   (
     {
@@ -54,6 +31,7 @@ export const QuickActionCard = forwardRef<HTMLAnchorElement | HTMLDivElement, Qu
       href,
       size = 'md',
       target = '_self',
+      responsiveLayout = true,
       ...props
     },
     ref
@@ -61,11 +39,15 @@ export const QuickActionCard = forwardRef<HTMLAnchorElement | HTMLDivElement, Qu
     const content = (
       <>
         {Icon && (
-          <div className={cn(iconSizeStyles[size], 'rounded-lg flex items-center justify-center flex-shrink-0', iconBgColor)}>
-            <Icon className={cn(iconInnerSizeStyles[size], iconColor)} />
+          <div className={cn(getContainerSize(size), 'rounded-lg flex items-center justify-center flex-shrink-0', iconBgColor)}>
+            <Icon className={cn(getIconSize(size), iconColor)} />
           </div>
         )}
-        <span className={cn('font-medium text-foreground group-hover:text-primary transition-colors', labelSizeStyles[size])}>
+        <span className={cn(
+          'font-medium text-foreground group-hover:text-primary transition-colors',
+          getTextSize(size),
+          responsiveLayout && 'text-center sm:text-left'
+        )}>
           {label}
         </span>
       </>
@@ -73,9 +55,10 @@ export const QuickActionCard = forwardRef<HTMLAnchorElement | HTMLDivElement, Qu
 
     const baseClasses = cn(
       'bg-card border border-border rounded-xl',
-      'flex items-center',
-      'hover:border-primary/50 transition-colors group',
-      sizeStyles[size],
+      responsiveLayout ? 'flex flex-col sm:flex-row items-center justify-center sm:justify-start' : 'flex items-center',
+      'hover:border-primary/50 hover:shadow-md transition-all duration-200 group',
+      getSpacing('p', size),
+      getGap(size === 'sm' ? 'sm' : size),
       className
     );
 

package/src/presentation/organisms/StatCard.tsx

@@ -1,11 +1,11 @@
 /**
  * StatCard Component (Organism)
- * @description Enhanced metric card with progress bar and target tracking
+ * @description Enhanced metric card with progress bar and target tracking (Responsive)
  * Combines functionality of KPICard and StatsCard from main app
  */
 
 import { forwardRef, type ComponentType } from 'react';
-import { cn } from '../../infrastructure/utils';
+import { cn, getSpacing, getIconSize, getContainerSize, getTextSize, getSpaceY, getGap } from '../../infrastructure/utils';
 import { Card, CardContent } from './Card';
 import { Progress } from '../atoms';
 import { ArrowUpRight, ArrowDownRight } from 'lucide-react';
@@ -28,39 +28,10 @@ export interface StatCardProps extends BaseProps {
   variant?: 'default' | 'gradient' | 'elevated';
   trendValueFormatter?: (value: number) => string;
   onClick?: () => void;
-  changeLabel?: string; // For backward compatibility with StatsCard
+  changeLabel?: string;
+  responsiveLayout?: boolean;
 }
 
-const sizeStyles = {
-  sm: 'p-3',
-  md: 'p-4',
-  lg: 'p-6',
-};
-
-const valueSizeStyles = {
-  sm: 'text-lg',
-  md: 'text-2xl',
-  lg: 'text-3xl',
-};
-
-const iconSizeStyles = {
-  sm: 'h-4 w-4',
-  md: 'h-8 w-8',
-  lg: 'h-12 w-12',
-};
-
-const labelSizeStyles = {
-  sm: 'text-xs',
-  md: 'text-sm',
-  lg: 'text-base',
-};
-
-const iconBgSizeStyles = {
-  sm: 'w-8 h-8',
-  md: 'w-12 h-12',
-  lg: 'w-16 h-16',
-};
-
 export const StatCard = forwardRef<HTMLDivElement, StatCardProps>(
   (
     {
@@ -76,14 +47,15 @@ export const StatCard = forwardRef<HTMLDivElement, StatCardProps>(
       trendValueFormatter = (v) => `${v > 0 ? '+' : ''}${Math.abs(v).toFixed(1)}%`,
       onClick,
       changeLabel,
+      responsiveLayout = true,
       ...props
     },
     ref
   ) => {
     const isPositive = trend?.value !== undefined && trend.value >= 0;
     const GrowthIcon = isPositive ? ArrowUpRight : ArrowDownRight;
-    const trendColor = isPositive ? 'text-green-600' : 'text-red-600';
-    const iconBgColor = isPositive ? 'text-green-500' : 'text-red-500';
+    const trendColor = isPositive ? 'text-green-600 dark:text-green-400' : 'text-red-600 dark:text-red-400';
+    const iconBgColor = isPositive ? 'text-green-500 dark:text-green-400' : 'text-red-500 dark:text-red-400';
 
     const cardVariant = variant === 'elevated' ? 'elevated' : 'default';
 
@@ -93,32 +65,37 @@ export const StatCard = forwardRef<HTMLDivElement, StatCardProps>(
         variant={cardVariant}
         className={cn(
           'transition-all duration-300',
-          variant === 'gradient' && 'bg-gradient-to-br from-white to-gray-50 hover:shadow-lg border-0 shadow-md',
+          variant === 'gradient' && 'bg-gradient-to-br from-white to-gray-50 dark:from-gray-800 dark:to-gray-900 hover:shadow-lg border-0 shadow-md',
           onClick && 'cursor-pointer hover:shadow-lg hover:border-primary/50',
           className
         )}
         onClick={onClick}
         {...props}
       >
-        <CardContent className={cn(sizeStyles[size])}>
-          <div className="flex items-center justify-between mb-4">
+        <CardContent className={getSpacing('p', size)}>
+          <div className={cn(
+            'flex items-center justify-between mb-4',
+            getGap('md'),
+            'flex-col sm:flex-row sm:mb-6'
+          )}>
             {Icon && (
               <div
                 className={cn(
                   'rounded-xl flex items-center justify-center',
                   variant === 'gradient' && 'bg-gradient-to-br from-teal-500 to-cyan-500',
                   variant !== 'gradient' && `bg-${iconColor.split('-')[1]}-500/10`,
-                  iconBgSizeStyles[size]
+                  getContainerSize(size),
+                  responsiveLayout && 'w-full sm:w-auto'
                 )}
               >
-                <Icon className={cn(iconSizeStyles[size], variant === 'gradient' ? 'text-white' : iconColor)} />
+                <Icon className={cn(getIconSize(size), variant === 'gradient' ? 'text-white' : iconColor)} />
               </div>
             )}
             {trend && (
               <span
                 className={cn(
-                  'text-sm font-medium px-2 py-1 rounded-full',
-                  isPositive ? 'text-green-700 bg-green-100' : 'text-red-700 bg-red-100'
+                  'text-xs sm:text-sm font-medium px-2 py-1 rounded-full whitespace-nowrap',
+                  isPositive ? 'text-green-700 bg-green-100 dark:text-green-300 dark:bg-green-900/30' : 'text-red-700 bg-red-100 dark:text-red-300 dark:bg-red-900/30'
                 )}
               >
                 {changeLabel || trendValueFormatter(trend.value)}
@@ -126,29 +103,34 @@ export const StatCard = forwardRef<HTMLDivElement, StatCardProps>(
             )}
           </div>
 
-          <div className="space-y-3">
-            <div>
-              <p className={cn('font-bold text-gray-900', valueSizeStyles[size])}>
+          <div className={getSpaceY('md')}>
+            <div className={cn(
+              responsiveLayout && 'text-center sm:text-left'
+            )}>
+              <p className={cn('font-bold text-gray-900 dark:text-gray-100', size === 'sm' ? 'text-lg sm:text-xl' : size === 'md' ? 'text-2xl sm:text-3xl' : 'text-3xl sm:text-4xl')}>
                 {typeof value === 'number' ? value.toLocaleString() : value}
               </p>
-              <p className={cn('text-muted-foreground', labelSizeStyles[size])}>{title}</p>
+              <p className={cn('text-muted-foreground', getTextSize(size))}>{title}</p>
             </div>
 
             {target && (
-              <div className="space-y-1">
-                <div className="flex justify-between text-xs">
+              <div className={getSpaceY('sm')}>
+                <div className="flex justify-between text-xs sm:text-sm">
                   <span className="text-muted-foreground">Target: {target.value}</span>
-                  <span className="text-teal-600">{target.progress}%</span>
+                  <span className="text-teal-600 dark:text-teal-400 font-medium">{target.progress}%</span>
                 </div>
-                <Progress value={target.progress} className="h-2" />
+                <Progress value={target.progress} className="h-2 sm:h-2.5" />
               </div>
             )}
 
             {trend && variant !== 'gradient' && (
-              <div className="flex items-center mt-1">
-                <GrowthIcon className={cn('h-3 w-3 mr-1', iconBgColor)} />
-                <p className={cn('text-xs', trendColor)}>{trendValueFormatter(trend.value)}</p>
-                {trend.label && <p className="text-xs text-muted-foreground ml-1">{trend.label}</p>}
+              <div className={cn(
+                'flex items-center mt-1',
+                responsiveLayout && 'justify-center sm:justify-start'
+              )}>
+                <GrowthIcon className={cn('h-3 w-3 sm:h-4 sm:w-4 mr-1', iconBgColor)} />
+                <p className={cn('text-xs sm:text-sm', trendColor)}>{trendValueFormatter(trend.value)}</p>
+                {trend.label && <p className="text-xs text-muted-foreground ml-1 hidden xs:inline">{trend.label}</p>}
               </div>
             )}
           </div>

package/src/presentation/organisms/index.ts

@@ -92,6 +92,9 @@ export type { StatCardProps } from './StatCard';
 export { FormModal } from './FormModal';
 export type { FormModalProps } from './FormModal';
 
+export { Grid, GridItem } from './Grid';
+export type { GridProps, GridItemProps } from './Grid';
+
 export { ConfirmDialog } from './ConfirmDialog';
 export type { ConfirmDialogProps } from './ConfirmDialog';