@umituz/web-design-system 2.8.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-design-system",
-  "version": "2.8.0",
+  "version": "3.0.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

@@ -1,243 +1,224 @@
 /**
- * Responsive Design Tokens
- * @description Centralized mapping of size variants to Tailwind spacing scale values
+ * Responsive Design Tokens (Formula-Based)
+ * @description Centralized responsive scale generation using formulas
  *
- * 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 values are generated dynamically from base values and formulas.
+ * This provides ZERO code duplication and single source of truth.
  *
- * All responsive calculations are centralized here - components should NOT
- * define their own size styles or do any spacing calculations.
+ * To modify responsive behavior:
+ * 1. Change base values (BASE_* constants)
+ * 2. Modify formula functions (*Formula)
+ * 3. Entire system updates automatically
  */
 
 import type { SizeVariant, Breakpoint } from '../types';
+import { SPACING_SCALE } from '../../infrastructure/constants/spacing.constants';
+import { TEXT_SIZES, type TextSizeKey } from '../../infrastructure/constants/typography.constants';
+import { BREAKPOINT_ORDER } from '../../infrastructure/constants/breakpoint.constants';
 
 /**
- * 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;
+ * Type for scale generation formula
+ * Input: base value for size variant, current breakpoint
+ * Output: spacing scale index (as number, will be converted to string)
+ */
+type ScaleFormula = (base: number, breakpoint: Breakpoint) => number;
+
+/**
+ * Type for generator result
+ */
+type ResponsiveScale = Record<SizeVariant, Partial<Record<Breakpoint, string>>>;
+
+// ============================================================================
+// BASE VALUES - Single source of truth for size variants
+// ============================================================================
+
+/**
+ * Base spacing values for each size variant
+ * Defines the starting point for responsive spacing calculation
+ */
+const SPACING_BASES: Record<SizeVariant, number> = {
+  xs: 1, // SPACING_SCALE['1'] = 4px
+  sm: 2, // SPACING_SCALE['2'] = 8px
+  md: 3, // SPACING_SCALE['3'] = 12px
+  lg: 4, // SPACING_SCALE['4'] = 16px
+  xl: 5, // SPACING_SCALE['5'] = 20px
+};
+
+/**
+ * Base icon size values for each size variant
+ */
+const ICON_BASES: Record<SizeVariant, number> = {
+  xs: 4,
+  sm: 5,
+  md: 6,
+  lg: 8,
+  xl: 10,
+};
+
+/**
+ * Base container size values (for icon wrappers)
+ */
+const CONTAINER_BASES: Record<SizeVariant, number> = {
+  xs: 6,
+  sm: 8,
+  md: 10,
+  lg: 12,
+  xl: 14,
+};
+
+/**
+ * Base gap/spacing values for layout
+ */
+const GAP_BASES: Record<SizeVariant, number> = {
+  xs: 1,
+  sm: 2,
+  md: 3,
+  lg: 4,
+  xl: 5,
+};
+
+// ============================================================================
+// FORMULAS - Define responsive behavior for each token type
+// ============================================================================
+
+/**
+ * Spacing formula for padding, margin, gap
+ * Progression: xs/sm→base, md/lg→base+1, xl→base+2, 2xl→base+3
+ */
+const spacingFormula: ScaleFormula = (base, bp) => {
+  const bpIndex = BREAKPOINT_ORDER.indexOf(bp);
+  if (bpIndex <= 1) return base; // xs, sm
+  if (bpIndex <= 3) return base + 1; // md, lg
+  if (bpIndex === 4) return base + 2; // xl
+  return base + 3; // 2xl
+};
+
+/**
+ * Icon size formula
+ * Progression: More gradual increase across breakpoints
+ */
+const iconFormula: ScaleFormula = (base, bp) => {
+  const bpIndex = BREAKPOINT_ORDER.indexOf(bp);
+  if (bp === 'xs') return base - 1;
+  if (bp === 'sm') return base;
+  if (bp === 'md') return base + 1;
+  if (bp === 'lg') return base + 2;
+  if (bp === 'xl') return base + 3;
+  return base + 3; // 2xl
+};
+
+/**
+ * Container size formula (for icon wrappers)
+ * Consistent size increase
+ */
+const containerFormula: ScaleFormula = (base, bp) => {
+  const bpIndex = BREAKPOINT_ORDER.indexOf(bp);
+  if (bpIndex <= 3) return base + 2; // xs, sm, md, lg
+  if (bpIndex === 4) return base + 2; // xl
+  return base + 2; // 2xl
+};
+
+/**
+ * Gap formula for layout spacing
+ */
+const gapFormula: ScaleFormula = (base, bp) => {
+  const bpIndex = BREAKPOINT_ORDER.indexOf(bp);
+  if (bpIndex <= 1) return base; // xs, sm
+  if (bpIndex <= 3) return base + 1; // md, lg
+  if (bpIndex === 4) return base + 1; // xl
+  return base + 2; // 2xl
+};
+
+// ============================================================================
+// GENERATORS - Create responsive scales dynamically
+// ============================================================================
+
+/**
+ * Generate responsive scale for any token type
+ * @param bases - Base values for each size variant
+ * @param formula - Formula to calculate value at each breakpoint
+ * @returns Complete responsive scale object
+ */
+function generateResponsiveScale(
+  bases: Record<SizeVariant, number>,
+  formula: ScaleFormula
+): ResponsiveScale {
+  const result: Partial<ResponsiveScale> = {};
+
+  for (const size of Object.keys(bases) as SizeVariant[]) {
+    const base = bases[size];
+    result[size] = {};
+
+    for (const bp of BREAKPOINT_ORDER) {
+      const scaleIndex = formula(base, bp);
+      const scaleKey = scaleIndex.toString() as keyof typeof SPACING_SCALE;
+
+      // Validate and get spacing scale value
+      if (scaleKey in SPACING_SCALE) {
+        result[size]![bp] = SPACING_SCALE[scaleKey];
+      }
+    }
+  }
+
+  return result as ResponsiveScale;
+}
+
+/**
+ * Generate responsive text sizes
+ * Text sizes use string literals, not spacing scale
+ */
+function generateResponsiveTextSizes() {
+  const textSizeKeys: Record<SizeVariant, { mobile: TextSizeKey; tablet: TextSizeKey }> = {
+    xs: { mobile: 'xs', tablet: 'xs' },
+    sm: { mobile: 'xs', tablet: 'sm' },
+    md: { mobile: 'sm', tablet: 'base' },
+    lg: { mobile: 'base', tablet: 'lg' },
+    xl: { mobile: 'lg', tablet: 'xl' },
+  };
+
+  const result: Partial<Record<SizeVariant, Partial<Record<'mobile' | 'tablet', string>>>> = {};
+
+  for (const size of Object.keys(textSizeKeys) as SizeVariant[]) {
+    const keys = textSizeKeys[size];
+    result[size] = {
+      mobile: TEXT_SIZES[keys.mobile],
+      tablet: `sm:${TEXT_SIZES[keys.tablet]}`,
+    };
+  }
+
+  return result as Record<SizeVariant, Partial<Record<'mobile' | 'tablet', string>>>;
+}
+
+// ============================================================================
+// EXPORTS - All responsive tokens (one line each!)
+// ============================================================================
+
+/**
+ * Responsive spacing scale for padding, margin, space-*, gap-*
+ */
+export const RESPONSIVE_SPACING = generateResponsiveScale(SPACING_BASES, spacingFormula);
+
+/**
+ * Responsive icon sizes (height/width)
+ */
+export const RESPONSIVE_ICON_SIZE = generateResponsiveScale(ICON_BASES, iconFormula);
+
+/**
+ * Responsive container sizes for icon wrappers
+ */
+export const RESPONSIVE_CONTAINER_SIZE = generateResponsiveScale(CONTAINER_BASES, containerFormula);
+
+/**
+ * Responsive gap/spacing for layouts
+ */
+export const RESPONSIVE_GAP = generateResponsiveScale(GAP_BASES, gapFormula);
+
+/**
+ * Responsive text sizes (mobile + tablet)
+ */
+export const RESPONSIVE_TEXT_SIZE = generateResponsiveTextSizes();
+
+/**
+ * Type exports
+ */
+export type SpacingScale = keyof typeof SPACING_SCALE;

package/src/domain/types/component.types.ts

@@ -4,8 +4,9 @@
  */
 
 import type { ReactNode } from 'react';
+import type { SizeVariant } from '../../infrastructure/constants/size-variant.constants';
 
-export type SizeVariant = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export { type SizeVariant } from '../../infrastructure/constants/size-variant.constants';
 export type ColorVariant = 'primary' | 'secondary' | 'success' | 'warning' | 'destructive';
 export type ColorScheme = 'light' | 'dark';
 

package/src/infrastructure/constants/index.ts

@@ -21,3 +21,33 @@ export {
   isBreakpointGreaterThan,
   isBreakpointLessThan,
 } from './breakpoint.constants';
+
+export {
+  SPACING_SCALE,
+  COMMON_SPACING,
+  SIZE_SPACING,
+  type SpacingScaleKey,
+  type SpacingScale,
+  isValidSpacing,
+} from './spacing.constants';
+
+export {
+  SIZE_VARIANTS,
+  SIZE_VARIANT_ORDER,
+  getNextSizeVariant,
+  getPrevSizeVariant,
+  type SizeVariantKey,
+  type SizeVariant,
+  isValidSizeVariant,
+} from './size-variant.constants';
+
+export {
+  TEXT_SIZES,
+  FONT_WEIGHTS,
+  COMMON_TEXT_SIZES,
+  TEXT_SIZE_BY_VARIANT,
+  type TextSizeKey,
+  type TextSize,
+  type FontWeightKey,
+  type FontWeight,
+} from './typography.constants';

package/src/infrastructure/constants/size-variant.constants.ts

@@ -0,0 +1,63 @@
+/**
+ * Size Variant Constants
+ * @description Size variants used throughout the design system
+ *
+ * All size variant values are defined here to provide consistency
+ * and prevent hardcoded strings in components.
+ */
+
+/**
+ * Size variants available in the design system
+ * Ordered from smallest to largest
+ */
+export const SIZE_VARIANTS = {
+  xs: 'xs',
+  sm: 'sm',
+  md: 'md',
+  lg: 'lg',
+  xl: 'xl',
+} as const;
+
+/**
+ * Type for size variant keys
+ */
+export type SizeVariantKey = keyof typeof SIZE_VARIANTS;
+
+/**
+ * Type for size variant values
+ */
+export type SizeVariant = typeof SIZE_VARIANTS[SizeVariantKey];
+
+/**
+ * Size variant order (for sorting/comparison)
+ */
+export const SIZE_VARIANT_ORDER: SizeVariant[] = ['xs', 'sm', 'md', 'lg', 'xl'];
+
+/**
+ * Get the next larger size variant
+ */
+export function getNextSizeVariant(current: SizeVariant): SizeVariant | null {
+  const index = SIZE_VARIANT_ORDER.indexOf(current);
+  if (index === -1 || index === SIZE_VARIANT_ORDER.length - 1) {
+    return null;
+  }
+  return SIZE_VARIANT_ORDER[index + 1];
+}
+
+/**
+ * Get the next smaller size variant
+ */
+export function getPrevSizeVariant(current: SizeVariant): SizeVariant | null {
+  const index = SIZE_VARIANT_ORDER.indexOf(current);
+  if (index <= 0) {
+    return null;
+  }
+  return SIZE_VARIANT_ORDER[index - 1];
+}
+
+/**
+ * Validate if a value is a valid size variant
+ */
+export function isValidSizeVariant(value: string): value is SizeVariant {
+  return Object.values(SIZE_VARIANTS).includes(value as SizeVariant);
+}

package/src/infrastructure/constants/spacing.constants.ts

@@ -0,0 +1,92 @@
+/**
+ * Spacing Constants
+ * @description Tailwind CSS spacing scale values
+ * @see https://tailwindcss.com/docs/customizing-spacing
+ *
+ * All spacing values used in the design system are defined here.
+ * This provides a single source of truth for spacing scale.
+ */
+
+/**
+ * Tailwind CSS spacing scale
+ * Each value represents a spacing unit that maps to a specific pixel value
+ * Format: Key is the spacing class name, value is the unit number (as string for Tailwind class construction)
+ */
+export const SPACING_SCALE = {
+  '0': '0',   // 0px
+  '0.5': '0.5', // 2px
+  '1': '1',   // 4px
+  '1.5': '1.5', // 6px
+  '2': '2',   // 8px
+  '2.5': '2.5', // 10px
+  '3': '3',   // 12px
+  '3.5': '3.5', // 14px
+  '4': '4',   // 16px
+  '5': '5',   // 20px
+  '6': '6',   // 24px
+  '7': '7',   // 28px
+  '8': '8',   // 32px
+  '9': '9',   // 36px
+  '10': '10', // 40px
+  '11': '11', // 44px
+  '12': '12', // 48px
+  '14': '14', // 56px
+  '16': '16', // 64px
+  '20': '20', // 80px
+  '24': '24', // 96px
+  '28': '28', // 112px
+  '32': '32', // 128px
+  '36': '36', // 144px
+  '40': '40', // 160px
+  '44': '44', // 176px
+  '48': '48', // 192px
+  '52': '52', // 208px
+  '56': '56', // 224px
+  '60': '60', // 240px
+  '64': '64', // 256px
+  '72': '72', // 288px
+  '80': '80', // 320px
+  '96': '96', // 384px
+} as const;
+
+/**
+ * Type for spacing scale keys
+ */
+export type SpacingScaleKey = keyof typeof SPACING_SCALE;
+
+/**
+ * Type for spacing scale values (string format for Tailwind classes)
+ */
+export type SpacingScale = `${SpacingScaleKey}`;
+
+/**
+ * Common spacing values used throughout the design system
+ * These are frequently used spacing values
+ */
+export const COMMON_SPACING = {
+  xs: SPACING_SCALE['1'],
+  sm: SPACING_SCALE['2'],
+  md: SPACING_SCALE['4'],
+  lg: SPACING_SCALE['6'],
+  xl: SPACING_SCALE['8'],
+  '2xl': SPACING_SCALE['12'],
+} as const;
+
+/**
+ * Spacing scale for component sizing
+ */
+export const SIZE_SPACING = {
+  xs: SPACING_SCALE['3'],
+  sm: SPACING_SCALE['4'],
+  md: SPACING_SCALE['5'],
+  lg: SPACING_SCALE['6'],
+  xl: SPACING_SCALE['8'],
+  '2xl': SPACING_SCALE['10'],
+} as const;
+
+/**
+ * Validate if a value is a valid spacing scale
+ */
+export function isValidSpacing(value: string): value is SpacingScale {
+  return Object.keys(SPACING_SCALE).includes(value);
+}

package/src/infrastructure/constants/typography.constants.ts

@@ -0,0 +1,101 @@
+/**
+ * Typography Constants
+ * @description Typography scale values for the design system
+ *
+ * All font size and text utility values are defined here.
+ * This provides consistency with Tailwind's default typography scale.
+ */
+
+/**
+ * Text size utilities (Tailwind text classes)
+ */
+export const TEXT_SIZES = {
+  xs: 'text-xs',       // 0.75rem (12px)
+  sm: 'text-sm',       // 0.875rem (14px)
+  base: 'text-base',   // 1rem (16px)
+  lg: 'text-lg',       // 1.125rem (18px)
+  xl: 'text-xl',       // 1.25rem (20px)
+  '2xl': 'text-2xl',   // 1.5rem (24px)
+  '3xl': 'text-3xl',   // 1.875rem (30px)
+  '4xl': 'text-4xl',   // 2.25rem (36px)
+  '5xl': 'text-5xl',   // 3rem (48px)
+  '6xl': 'text-6xl',   // 3.75rem (60px)
+  '7xl': 'text-7xl',   // 4.5rem (72px)
+  '8xl': 'text-8xl',   // 6rem (96px)
+  '9xl': 'text-9xl',   // 8rem (128px)
+} as const;
+
+/**
+ * Type for text size keys
+ */
+export type TextSizeKey = keyof typeof TEXT_SIZES;
+
+/**
+ * Type for text size values
+ */
+export type TextSize = typeof TEXT_SIZES[TextSizeKey];
+
+/**
+ * Font weight utilities
+ */
+export const FONT_WEIGHTS = {
+  thin: 'font-thin',       // 100
+  extralight: 'font-extralight', // 200
+  light: 'font-light',     // 300
+  normal: 'font-normal',   // 400
+  medium: 'font-medium',   // 500
+  semibold: 'font-semibold', // 600
+  bold: 'font-bold',       // 700
+  extrabold: 'font-extrabold', // 800
+  black: 'font-black',     // 900
+} as const;
+
+/**
+ * Type for font weight keys
+ */
+export type FontWeightKey = keyof typeof FONT_WEIGHTS;
+
+/**
+ * Type for font weight values
+ */
+export type FontWeight = typeof FONT_WEIGHTS[FontWeightKey];
+
+/**
+ * Common text sizes for different element types
+ */
+export const COMMON_TEXT_SIZES = {
+  caption: TEXT_SIZES.xs,
+  small: TEXT_SIZES.sm,
+  body: TEXT_SIZES.base,
+  subtitle: TEXT_SIZES.lg,
+  title: TEXT_SIZES.xl,
+  heading: TEXT_SIZES['2xl'],
+  display: TEXT_SIZES['4xl'],
+} as const;
+
+/**
+ * Text sizes by size variant
+ * Maps size variants to appropriate text sizes
+ */
+export const TEXT_SIZE_BY_VARIANT = {
+  xs: {
+    mobile: TEXT_SIZES.xs,
+    tablet: TEXT_SIZES.xs,
+  },
+  sm: {
+    mobile: TEXT_SIZES.xs,
+    tablet: TEXT_SIZES.sm,
+  },
+  md: {
+    mobile: TEXT_SIZES.sm,
+    tablet: TEXT_SIZES.base,
+  },
+  lg: {
+    mobile: TEXT_SIZES.base,
+    tablet: TEXT_SIZES.lg,
+  },
+  xl: {
+    mobile: TEXT_SIZES.lg,
+    tablet: TEXT_SIZES.xl,
+  },
+} as const;