@juspay/blend-design-system 0.0.37-beta.2 → 0.0.37-beta.4

package/lib/components/Modal/accessibility/ModalAccessibilityReport.ts

@@ -0,0 +1,350 @@
+/**
+ * Modal Component Accessibility Report Data
+ * WCAG 2.0, 2.1, 2.2 (Level A, AA, AAA) Compliance Analysis
+ *
+ * Note: Items marked with "unsure" require manual verification
+ * Color contrast ratios should be verified using actual color values from theme tokens
+ */
+
+import type { AccessibilityReport } from '../../Button/accessibility/ButtonAccessibilityReport'
+
+export const modalAccessibilityReport: AccessibilityReport = {
+    componentName: 'Modal',
+    wcagVersion: '2.2',
+    reportDate: new Date().toISOString().split('T')[0],
+    conformanceLevel: 'Level AA',
+    overallStatus: 'partial',
+    summary:
+        'The Modal component demonstrates strong compliance with WCAG 2.0, 2.1, and 2.2 standards at Level A and AA. The component provides comprehensive accessibility features including proper ARIA attributes (role="dialog", aria-modal="true", aria-labelledby, aria-describedby), keyboard navigation (Tab, Shift+Tab, Escape), focus management (focus trap, focus return), and screen reader support. Modal content is properly labeled, focus is trapped within the modal when open, and focus returns to the trigger element when closed. Decorative icons and backdrop are properly hidden with aria-hidden="true" and role="presentation". Some contrast ratios require manual verification. This report evaluates criteria from WCAG 2.0, 2.1, and 2.2 guidelines. The component fully meets Level A requirements, fully meets Level AA requirements (with some items requiring verification), and partially meets Level AAA requirements. Currently compliant AAA criteria: 1.4.8 Visual Presentation, 2.1.3 Keyboard (No Exception), 3.2.5 Change on Request. Non-compliant AAA criteria: 1.4.6 Contrast (Enhanced) - requires 7:1 contrast ratio. To achieve full AAA compliance, text and background colors need to be adjusted to meet 7:1 contrast ratio (currently designed for AA standard of 4.5:1).',
+    criteria: [
+        {
+            id: '1.1.1',
+            level: 'A',
+            title: 'Non-text Content',
+            status: 'compliant',
+            description:
+                'All non-text content has text alternatives. Decorative icons must be marked as such.',
+            implementation:
+                'Close button icon has aria-hidden="true". Backdrop has aria-hidden="true" and role="presentation". Modal title and subtitle provide accessible text content. Confirmed in Modal.tsx and MobileModal.tsx.',
+            testResults:
+                'Verified: Decorative icons and backdrop properly hidden. Modal text content provides accessible alternatives. Implementation confirmed in Modal.tsx and Modal.accessibility.test.tsx.',
+        },
+        {
+            id: '1.3.1',
+            level: 'A',
+            title: 'Info and Relationships',
+            status: 'compliant',
+            description:
+                'Information, structure, and relationships conveyed through presentation can be programmatically determined.',
+            implementation:
+                'Modal has role="dialog" and aria-modal="true". Title is linked via aria-labelledby. Subtitle is linked via aria-describedby when present. Modal structure maintains logical relationships. Confirmed in Modal.tsx.',
+            testResults:
+                'Verified: Proper semantic structure and ARIA relationships. Role assignment and title/subtitle relationships confirmed in Modal.tsx.',
+        },
+        {
+            id: '1.3.2',
+            level: 'A',
+            title: 'Meaningful Sequence',
+            status: 'compliant',
+            description:
+                'When the sequence in which content is presented affects its meaning, a correct reading sequence can be programmatically determined.',
+            implementation:
+                'Modal content follows logical reading order: header (title, subtitle, close button) → body content → footer (actions). DOM order matches visual order. Confirmed in Modal.tsx.',
+            testResults:
+                'Verified: Logical sequence maintained in component implementation.',
+        },
+        {
+            id: '1.3.3',
+            level: 'A',
+            title: 'Sensory Characteristics',
+            status: 'compliant',
+            description:
+                'Instructions provided for understanding and operating content do not rely solely on sensory characteristics.',
+            implementation:
+                'Modal functionality does not rely solely on shape, size, or visual location. Text labels provide context. Close button has aria-label. Action buttons have text labels.',
+            testResults: 'Verified: Not dependent on sensory characteristics.',
+        },
+        {
+            id: '1.3.4',
+            level: 'AA',
+            title: 'Orientation',
+            status: 'compliant',
+            description:
+                'Content does not restrict its view and operation to a single display orientation.',
+            implementation:
+                'Modal works in both portrait and landscape orientations. MobileModal provides drawer-style modal for mobile devices. Responsive design adapts to different screen sizes and orientations.',
+            testResults: 'Verified: Component functions in all orientations.',
+        },
+        {
+            id: '1.4.3',
+            level: 'AA',
+            title: 'Contrast (Minimum)',
+            status: 'unsure',
+            description:
+                'Text and images of text have a contrast ratio of at least 4.5:1 for normal text, 3:1 for large text.',
+            implementation:
+                'Modal text uses theme colors. Title, subtitle, and body text colors vary. Background colors from modal tokens. Contrast ratios should be verified using actual color values from theme tokens.',
+            testResults:
+                'UNSURE: Requires manual contrast ratio calculation. Modal text and background color combinations should be verified using WebAIM Contrast Checker or similar tool. VERIFICATION REQUIRED.',
+            notes: 'Contrast ratios must be verified using tools like WebAIM Contrast Checker. Current implementation targets AA standard (4.5:1). For AAA compliance, contrast ratio must be 7:1.',
+        },
+        {
+            id: '1.4.6',
+            level: 'AAA',
+            title: 'Contrast (Enhanced)',
+            status: 'non-compliant',
+            description:
+                'Text and images of text have a contrast ratio of at least 7:1 for normal text, 4.5:1 for large text.',
+            implementation:
+                'Modal text and backgrounds are designed for AA contrast (4.5:1 per WCAG 1.4.3), reused from theme tokens.',
+            testResults:
+                'NON-COMPLIANT: Current color combinations are designed for AA standard (4.5:1 per WCAG 1.4.3) and do not meet AAA requirement (7:1 per WCAG 1.4.6). To achieve AAA compliance, text colors need to be adjusted to provide higher contrast ratios.',
+            notes: 'This is a Level AAA criterion per WCAG 1.4.6. Current implementation meets AA standard but not AAA. Manual contrast verification is required if AAA is a target.',
+        },
+        {
+            id: '1.4.8',
+            level: 'AAA',
+            title: 'Visual Presentation',
+            status: 'compliant',
+            description:
+                'Blocks of text can be presented without loss of content or functionality when text spacing and zoom are adjusted.',
+            implementation:
+                'Modal respects browser/system text size settings. Text uses relative units via tokens. Layout uses flexbox, allowing text to scale up to 200% without loss of functionality. Modal content scrolls appropriately at all zoom levels.',
+            testResults:
+                'COMPLIANT: Modal text scales properly with browser zoom up to 200%. Layout remains functional at all zoom levels. Modal content scrolls correctly. Verified through manual resizing.',
+        },
+        {
+            id: '2.1.1',
+            level: 'A',
+            title: 'Keyboard',
+            status: 'compliant',
+            description:
+                'All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes.',
+            implementation:
+                'Modal is fully keyboard accessible. Tab/Shift+Tab navigation within modal. Escape key closes modal. Enter/Space activate buttons. Focus is trapped within modal when open. All functionality available via keyboard. Confirmed in Modal.tsx.',
+            testResults:
+                'COMPLIANT: Full keyboard operability. Tab, Shift+Tab, Escape, Enter, Space keys all work correctly. No timing requirements. Verified in Modal.accessibility.test.tsx.',
+        },
+        {
+            id: '2.1.2',
+            level: 'A',
+            title: 'No Keyboard Trap',
+            status: 'compliant',
+            description:
+                'If keyboard focus can be moved to a component of the page using a keyboard interface, then focus can be moved away from that component using only a keyboard interface.',
+            implementation:
+                'Focus is trapped within modal when open (intentional). Escape key or action buttons allow closing modal and returning focus. Focus returns to trigger element when modal closes. No permanent keyboard trap. Confirmed in Modal.tsx.',
+            testResults:
+                'COMPLIANT: Focus trap is intentional and can be escaped via Escape key or action buttons. Focus returns to trigger when modal closes.',
+        },
+        {
+            id: '2.1.3',
+            level: 'AAA',
+            title: 'Keyboard (No Exception)',
+            status: 'compliant',
+            description:
+                'All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes.',
+            implementation:
+                'All modal functionality is fully keyboard accessible without timing requirements. Tab navigation, Escape key, Enter, Space all work without timing constraints. No mouse-dependent functionality. Confirmed in Modal.tsx.',
+            testResults:
+                'COMPLIANT: Full keyboard operability without exceptions. Tab, Shift+Tab, Escape, Enter, Space keys all work correctly. No timing requirements. No mouse-only functionality.',
+            notes: 'This is Level AAA enhancement of WCAG 2.1.1. The Modal component already meets this requirement as all functionality is keyboard accessible without timing constraints.',
+        },
+        {
+            id: '2.4.3',
+            level: 'A',
+            title: 'Focus Order',
+            status: 'compliant',
+            description:
+                'If a Web page can be navigated sequentially and the navigation sequences affect meaning or operation, focusable components receive focus in an order that preserves meaning and operability.',
+            implementation:
+                'Focus moves to first focusable element when modal opens. Focus order within modal is logical: close button → content → action buttons. Focus wraps from last to first element on Tab, and from first to last on Shift+Tab. Confirmed in Modal.tsx.',
+            testResults:
+                'COMPLIANT: Logical focus order maintained. Focus moves to first element on open, wraps correctly. Verified in Modal.accessibility.test.tsx.',
+        },
+        {
+            id: '2.4.6',
+            level: 'AA',
+            title: 'Headings and Labels',
+            status: 'compliant',
+            description: 'Headings and labels describe topic or purpose.',
+            implementation:
+                'Modal title clearly describes the modal purpose. Action buttons have clear text labels. Close button has aria-label="Close modal".',
+            testResults:
+                'Verified: Modal title and labels clearly describe purpose.',
+        },
+        {
+            id: '2.4.7',
+            level: 'AA',
+            title: 'Focus Visible',
+            status: 'compliant',
+            description:
+                'Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible.',
+            implementation:
+                'All focusable elements within modal have visible focus indicators. Focus indicators provided by browser default or custom styles. Focus remains visible during keyboard navigation.',
+            testResults:
+                'COMPLIANT: Focus indicators are visible on all focusable elements. Verified in Modal.accessibility.test.tsx.',
+        },
+        {
+            id: '2.5.8',
+            level: 'AA',
+            title: 'Target Size (Minimum)',
+            status: 'compliant',
+            description:
+                'The size of the target for pointer inputs is at least 24 by 24 CSS pixels.',
+            implementation:
+                'Close button meets 24x24px minimum. Action buttons meet minimum size requirements. All interactive elements within modal meet Level AA requirement.',
+            testResults:
+                'COMPLIANT: All interactive elements meet Level AA requirement (24x24px minimum per WCAG 2.5.8). Verified in Modal.accessibility.test.tsx.',
+            notes: 'This is a Level AA criterion per WCAG 2.5.8. For AAA compliance (WCAG 2.5.5), target size must be 44x44px minimum.',
+        },
+        {
+            id: '3.2.1',
+            level: 'A',
+            title: 'On Focus',
+            status: 'compliant',
+            description:
+                'Changing the setting of any user interface component does not automatically cause a change of context unless the user has been advised of the behavior before using the component.',
+            implementation:
+                'Focusing elements within modal does not cause unexpected context changes. Modal opening is user-initiated. No automatic form submission or navigation. Confirmed in Modal.tsx.',
+            testResults:
+                'COMPLIANT: Focus does not cause unexpected context changes.',
+        },
+        {
+            id: '3.2.2',
+            level: 'A',
+            title: 'On Input',
+            status: 'compliant',
+            description:
+                'Changing the setting of any user interface component does not automatically cause a change of context unless the user has been advised of the behavior before using the component.',
+            implementation:
+                'Interacting with modal elements does not cause unexpected context changes. Modal closing is user-initiated (Escape, action buttons, backdrop click). No automatic form submission or navigation. Confirmed in Modal.tsx.',
+            testResults:
+                'COMPLIANT: Input does not cause unexpected context changes.',
+        },
+        {
+            id: '3.2.5',
+            level: 'AAA',
+            title: 'Change on Request',
+            status: 'compliant',
+            description:
+                'Changes of context are initiated only by user request or a mechanism is available to turn off such changes.',
+            implementation:
+                'Modal opening/closing is initiated by user action (button click, Escape key, action buttons, backdrop click). No automatic context changes. Confirmed in Modal.tsx.',
+            testResults:
+                'COMPLIANT: All context changes are user-initiated. Modal behavior is predictable and user-controlled.',
+        },
+        {
+            id: '4.1.2',
+            level: 'A',
+            title: 'Name, Role, Value',
+            status: 'compliant',
+            description:
+                'For all user interface components, the name and role can be programmatically determined; states, properties, and values can be set programmatically; and notification of changes to these items is available to user agents, including assistive technologies.',
+            implementation:
+                'Modal has role="dialog" and aria-modal="true". Title provides accessible name via aria-labelledby. Subtitle provides description via aria-describedby when present. Close button has aria-label. Action buttons have accessible names via text. States (open/closed) are programmatically determinable. Confirmed in Modal.tsx.',
+            testResults:
+                'COMPLIANT: Proper role, name, and value. ARIA relationships established. States programmatically determinable.',
+        },
+    ],
+    strengths: [
+        'Proper ARIA attributes (role="dialog", aria-modal="true", aria-labelledby, aria-describedby)',
+        'Focus management: focus trap when open, focus return when closed',
+        'Full keyboard accessibility (Tab, Shift+Tab, Escape, Enter, Space)',
+        'Screen reader support with proper role and labeling',
+        'Focus wraps correctly from last to first and first to last',
+        'Proper handling of decorative icons and backdrop with aria-hidden',
+        'Mobile support with MobileModal drawer-style component',
+        'Scrollable content support',
+        'Works in all orientations',
+        'Text scales properly with browser zoom',
+        'Portal rendering ensures proper DOM hierarchy',
+        'Backdrop click to close (configurable)',
+        'Escape key to close',
+        'Action buttons with clear labels',
+    ],
+    recommendations: [
+        'Verify color contrast ratios using WebAIM Contrast Checker for all modal text/background combinations',
+        'For AAA compliance, adjust text colors to meet 7:1 contrast ratio requirement',
+        'Ensure all interactive elements meet minimum touch target size (24x24px for AA, 44x44px for AAA)',
+        'Test with multiple screen readers (VoiceOver, NVDA, JAWS) to verify announcements',
+        'Consider adding aria-live regions for dynamic modal content updates',
+        'Document modal best practices for content authors (clear titles, concise content)',
+        'Consider adding focus trap configuration options for advanced use cases',
+    ],
+    wcagVersions: {
+        '2.0': [
+            '1.1.1',
+            '1.3.1',
+            '1.3.2',
+            '1.3.3',
+            '1.4.3',
+            '1.4.6',
+            '1.4.8',
+            '2.1.1',
+            '2.1.2',
+            '2.4.3',
+            '2.4.6',
+            '2.4.7',
+            '3.2.1',
+            '3.2.2',
+            '4.1.2',
+        ],
+        '2.1': ['1.3.4', '2.1.3', '2.5.8', '3.2.5'],
+        '2.2': [],
+    },
+    testMethodology: {
+        automated: [
+            'jest-axe for automated accessibility violation detection',
+            'Modal.accessibility.test.tsx with 42 comprehensive test cases',
+            'Storybook a11y addon for interactive accessibility checks',
+            'Chromatic visual regression testing for modal states',
+        ],
+        manual: [
+            'Keyboard navigation testing (Tab, Shift+Tab, Escape)',
+            'Screen reader testing with VoiceOver (macOS) and NVDA (Windows)',
+            'Color contrast verification using WebAIM Contrast Checker',
+            'Focus indicator visibility testing',
+            'Focus trap verification',
+            'Focus return verification',
+            'Touch target size measurement using browser DevTools',
+            'Zoom testing up to 200%',
+            'Orientation testing (portrait/landscape)',
+            'Mobile device testing with MobileModal',
+        ],
+        verificationTools: [
+            'WebAIM Contrast Checker',
+            'axe DevTools',
+            'WAVE (Web Accessibility Evaluation Tool)',
+            'Lighthouse accessibility audit',
+            'Browser DevTools accessibility panel',
+        ],
+        wcagLevels: {
+            A: [
+                '1.1.1 Non-text Content',
+                '1.3.1 Info and Relationships',
+                '1.3.2 Meaningful Sequence',
+                '1.3.3 Sensory Characteristics',
+                '2.1.1 Keyboard',
+                '2.1.2 No Keyboard Trap',
+                '2.4.3 Focus Order',
+                '3.2.1 On Focus',
+                '3.2.2 On Input',
+                '4.1.2 Name, Role, Value',
+            ],
+            AA: [
+                '1.3.4 Orientation',
+                '1.4.3 Contrast (Minimum)',
+                '2.4.6 Headings and Labels',
+                '2.4.7 Focus Visible',
+                '2.5.8 Target Size (Minimum)',
+            ],
+            AAA: [
+                '1.4.6 Contrast (Enhanced)',
+                '1.4.8 Visual Presentation',
+                '2.1.3 Keyboard (No Exception)',
+                '3.2.5 Change on Request',
+            ],
+        },
+    },
+}

package/lib/components/Modal/index.ts

@@ -0,0 +1,3 @@
+export { default as Modal } from './Modal'
+export * from './modal.tokens'
+export * from './types'

package/lib/components/Modal/modal.animations.ts

@@ -0,0 +1,19 @@
+import { css } from 'styled-components'
+
+const easingIn = 'cubic-bezier(0.16, 0, 0.3, 1)'
+const easingOut = 'cubic-bezier(0.25, 0.46, 0.45, 0.94)'
+const duration = 300
+
+export const modalBackdropAnimations = (isAnimatingIn: boolean) => css`
+    transition: opacity ${duration}ms ${isAnimatingIn ? easingIn : easingOut};
+`
+
+export const modalContentAnimations = (isAnimatingIn: boolean) => css`
+    opacity: ${isAnimatingIn ? 1 : 0};
+    transform: scale(${isAnimatingIn ? 1 : 0.97});
+    transition:
+        opacity ${duration}ms ${isAnimatingIn ? easingIn : easingOut},
+        transform ${duration}ms ${isAnimatingIn ? easingIn : easingOut};
+`
+
+export const ANIMATION_DURATION = duration

package/lib/components/Modal/modal.tokens.ts

@@ -0,0 +1,207 @@
+import type { CSSObject } from 'styled-components'
+import { type FoundationTokenType } from '../../tokens/theme.token'
+import { type BreakpointType } from '../../breakpoints/breakPoints'
+
+export type ModalState = 'default'
+
+/**
+ * Modal Tokens following the pattern: [target].CSSProp.[state]
+ *
+ * Structure:
+ * - target: container | header | body | footer (defines what element the token applies to)
+ * - CSSProp: shadow | zIndex | borderRadius | padding | border | backgroundColor | fontSize | fontWeight | color | gap | alignItems
+ * - state: default (modal doesn't have interactive states)
+ *
+ * Pattern examples:
+ * - container.shadow
+ * - container.zIndex
+ * - container.borderRadius
+ * - header.padding
+ * - header.border
+ * - header.backgroundColor
+ * - header.text.title.fontSize
+ * - header.text.title.fontWeight
+ * - header.text.title.color
+ * - header.text.subtitle.fontSize
+ * - header.text.subtitle.color
+ * - body.padding
+ * - body.border
+ * - body.backgroundColor
+ * - footer.padding
+ * - footer.border
+ * - footer.backgroundColor
+ * - footer.alignItems
+ * - footer.gap
+ */
+export type ModalTokensType = {
+    // Pattern: shadow
+    boxShadow: CSSObject['boxShadow']
+    // Pattern: borderRadius
+    borderRadius: CSSObject['borderRadius']
+
+    overlay: {
+        backgroundColor: CSSObject['backgroundColor']
+    }
+
+    // Header properties
+    header: {
+        // Pattern: header.padding
+        padding: {
+            x: CSSObject['padding']
+            y: CSSObject['padding']
+        }
+        // Pattern: header.border
+        borderBottom: CSSObject['border']
+        // Pattern: header.backgroundColor
+        backgroundColor: CSSObject['backgroundColor']
+
+        // Text styling within header
+        text: {
+            title: {
+                // Pattern: header.text.title.color
+                color: CSSObject['color']
+                // Pattern: header.text.title.fontSize
+                fontSize: CSSObject['fontSize']
+                // Pattern: header.text.title.fontWeight
+                fontWeight: CSSObject['fontWeight']
+            }
+            subtitle: {
+                // Pattern: header.text.subtitle.color
+                color: CSSObject['color']
+                // Pattern: header.text.subtitle.fontSize
+                fontSize: CSSObject['fontSize']
+                // Pattern: header.text.subtitle.fontWeight
+                fontWeight: CSSObject['fontWeight']
+            }
+        }
+    }
+
+    // Body properties
+    body: {
+        // Pattern: body.padding
+        padding: CSSObject['padding']
+        // Pattern: body.backgroundColor
+        backgroundColor: CSSObject['backgroundColor']
+    }
+
+    // Footer properties
+    footer: {
+        // Pattern: footer.padding
+        padding: CSSObject['padding']
+        // Pattern: footer.border
+        borderTop: CSSObject['border']
+        // Pattern: footer.backgroundColor
+        backgroundColor: CSSObject['backgroundColor']
+        // Pattern: footer.gap
+        gap: CSSObject['gap']
+    }
+    closeButton: {
+        color: CSSObject['color'] // add hover and default state
+    }
+}
+
+export type ResponsiveModalTokens = {
+    [key in keyof BreakpointType]: ModalTokensType
+}
+
+export const getModalComponentTokens = (
+    foundationToken: FoundationTokenType
+): ResponsiveModalTokens => {
+    return {
+        sm: {
+            // Container properties
+            boxShadow: foundationToken.shadows.xs,
+            borderRadius: foundationToken.border.radius[12],
+            overlay: {
+                backgroundColor: 'rgba(0, 0, 0, 0.5)',
+            },
+            // Header properties
+            header: {
+                padding: {
+                    x: foundationToken.unit[16],
+                    y: foundationToken.unit[16],
+                },
+                borderBottom: `1px solid ${foundationToken.colors.gray[200]}`,
+                // borderRadius: foundationToken.border.radius[12],
+                backgroundColor: foundationToken.colors.gray[0],
+
+                text: {
+                    title: {
+                        color: foundationToken.colors.gray[700],
+                        fontSize: foundationToken.font.size.body.md.fontSize,
+                        fontWeight: foundationToken.font.weight[600],
+                    },
+                    subtitle: {
+                        color: foundationToken.colors.gray[600],
+                        fontSize: foundationToken.font.size.body.sm.fontSize,
+                        fontWeight: foundationToken.font.weight[400],
+                    },
+                },
+            },
+
+            // Body properties
+            body: {
+                padding: foundationToken.unit[16],
+                backgroundColor: foundationToken.colors.gray[0],
+            },
+
+            // Footer properties
+            footer: {
+                padding: foundationToken.unit[16],
+                borderTop: `1px solid ${foundationToken.colors.gray[200]}`,
+                backgroundColor: foundationToken.colors.gray[0],
+                gap: foundationToken.unit[12],
+            },
+            closeButton: {
+                color: foundationToken.colors.gray[500], // default color
+            },
+        },
+        lg: {
+            // Container properties
+            boxShadow: foundationToken.shadows.lg,
+            borderRadius: foundationToken.border.radius[16],
+            overlay: {
+                backgroundColor: 'rgba(0, 0, 0, 0.5)',
+            },
+            // Header properties
+            header: {
+                padding: {
+                    x: foundationToken.unit[20],
+                    y: foundationToken.unit[20],
+                },
+                borderBottom: `1px solid ${foundationToken.colors.gray[200]}`,
+                backgroundColor: foundationToken.colors.gray[0],
+
+                text: {
+                    title: {
+                        color: foundationToken.colors.gray[700],
+                        fontSize: foundationToken.font.size.body.lg.fontSize,
+                        fontWeight: foundationToken.font.weight[600],
+                    },
+                    subtitle: {
+                        color: foundationToken.colors.gray[600],
+                        fontSize: foundationToken.font.size.body.md.fontSize,
+                        fontWeight: foundationToken.font.weight[400],
+                    },
+                },
+            },
+
+            // Body properties
+            body: {
+                padding: foundationToken.unit[20],
+                backgroundColor: foundationToken.colors.gray[0],
+            },
+
+            // Footer properties
+            footer: {
+                padding: foundationToken.unit[20],
+                borderTop: `1px solid ${foundationToken.colors.gray[200]}`,
+                backgroundColor: foundationToken.colors.gray[0],
+                gap: foundationToken.unit[16],
+            },
+            closeButton: {
+                color: foundationToken.colors.gray[500], // default color
+            },
+        },
+    }
+}

package/lib/components/Modal/modal.utils.ts

@@ -0,0 +1,24 @@
+const PORTAL_ID = 'blend-modal-portal'
+
+export const getPortalContainer = (): HTMLElement => {
+    let portalContainer = document.getElementById(PORTAL_ID)
+
+    if (!portalContainer) {
+        portalContainer = document.createElement('div')
+        portalContainer.id = PORTAL_ID
+        portalContainer.style.position = 'relative'
+        portalContainer.style.zIndex = '101'
+        portalContainer.style.pointerEvents = 'auto'
+        document.body.appendChild(portalContainer)
+    }
+
+    return portalContainer
+}
+
+export const cleanupPortalContainer = (): void => {
+    const portalContainer = document.getElementById(PORTAL_ID)
+
+    if (portalContainer && portalContainer.children.length === 0) {
+        document.body.removeChild(portalContainer)
+    }
+}

package/lib/components/Modal/types.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react'
+import type { ButtonProps } from '../Button'
+import { SkeletonVariant } from '../Skeleton'
+
+type ModalButtonAction = Omit<ButtonProps, 'buttonGroupPosition'>
+
+type BodySkeletonProps = {
+    show?: boolean
+    width?: string
+    height?: string
+}
+
+export type ModalSkeletonProps = {
+    show?: boolean
+    variant?: SkeletonVariant
+    bodySkeletonProps?: BodySkeletonProps
+}
+
+export type ModalProps = {
+    isOpen: boolean
+    isCustom?: boolean
+    onClose: () => void
+    title?: string
+    subtitle?: string
+    children: ReactNode
+    primaryAction?: ModalButtonAction
+    secondaryAction?: ModalButtonAction
+    showCloseButton?: boolean
+    showHeader?: boolean
+    showFooter?: boolean
+    closeOnBackdropClick?: boolean
+    customHeader?: ReactNode
+    customFooter?: ReactNode
+    headerRightSlot?: ReactNode
+    showDivider?: boolean
+    minWidth?: string
+    useDrawerOnMobile?: boolean
+    skeleton?: ModalSkeletonProps
+    maxWidth?: string
+    maxHeight?: string
+    minHeight?: string
+}