gh-trabian-fluxwing-skills/skills/fluxwing-component-creator/templates/modal.md

Modal Dialog Component

Modal dialog overlay with focus management, backdrop, and configurable content areas for confirmations, forms, and content display.

Standard Modal (Medium Size)

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░░░┌────────────────────────────────┐░░░░░░░░
░░░░░░░░░░│ {{title}}                   │✕│░░░░░░░░
░░░░░░░░░░├────────────────────────────────┤░░░░░░░░
░░░░░░░░░░│                                │░░░░░░░░
░░░░░░░░░░│ {{content}}                    │░░░░░░░░
░░░░░░░░░░│                                │░░░░░░░░
░░░░░░░░░░│                                │░░░░░░░░
░░░░░░░░░░│                                │░░░░░░░░
░░░░░░░░░░├────────────────────────────────┤░░░░░░░░
░░░░░░░░░░│  ┌─────────┐  ┌─────────────┐  │░░░░░░░░
░░░░░░░░░░│  │ Cancel  │  │  {{buttons[1].text}}  │  │░░░░░░░░
░░░░░░░░░░│  └─────────┘  └─────────────┘  │░░░░░░░░
░░░░░░░░░░└────────────────────────────────┘░░░░░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

Small Modal (Confirmation)

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░┌──────────────────────────┐░░░░░
░░░░░░░░│ {{title}}             │✕│░░░░░
░░░░░░░░├──────────────────────────┤░░░░░
░░░░░░░░│                          │░░░░░
░░░░░░░░│ {{content}}              │░░░░░
░░░░░░░░│                          │░░░░░
░░░░░░░░├──────────────────────────┤░░░░░
░░░░░░░░│ ┌──────┐  ┌────────────┐ │░░░░░
░░░░░░░░│ │  No  │  │    Yes     │ │░░░░░
░░░░░░░░│ └──────┘  └────────────┘ │░░░░░
░░░░░░░░└──────────────────────────┘░░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

Large Modal (Form/Content)

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░┌────────────────────────────────────────────────────────┐░░░░░░░░
░░░░░░░░│ {{title}}                                            │✕│░░░░░░░░
░░░░░░░░├────────────────────────────────────────────────────────┤░░░░░░░░
░░░░░░░░│                                                        │░░░░░░░░
░░░░░░░░│ {{content}}                                            │░░░░░░░░
░░░░░░░░│                                                        │░░░░░░░░
░░░░░░░░│ Name: ┌─────────────────────────────────────────────┐  │░░░░░░░░
░░░░░░░░│       │ Enter your name                             │  │░░░░░░░░
░░░░░░░░│       └─────────────────────────────────────────────┘  │░░░░░░░░
░░░░░░░░│                                                        │░░░░░░░░
░░░░░░░░│ Email: ┌────────────────────────────────────────────┐  │░░░░░░░░
░░░░░░░░│        │ your@email.com                             │  │░░░░░░░░
░░░░░░░░│        └────────────────────────────────────────────┘  │░░░░░░░░
░░░░░░░░│                                                        │░░░░░░░░
░░░░░░░░├────────────────────────────────────────────────────────┤░░░░░░░░
░░░░░░░░│    ┌──────────┐  ┌──────────────┐  ┌──────────────┐    │░░░░░░░░
░░░░░░░░│    │  Cancel  │  │    Save      │  │   Submit     │    │░░░░░░░░
░░░░░░░░│    └──────────┘  └──────────────┘  └──────────────┘    │░░░░░░░░
░░░░░░░░└────────────────────────────────────────────────────────┘░░░░░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

Fullscreen Modal

╔══════════════════════════════════════════════════════════════════════════╗
║ {{title}}                                                             ✕ ║
╠══════════════════════════════════════════════════════════════════════════╣
║                                                                          ║
║ {{content}}                                                              ║
║                                                                          ║
║                                                                          ║
║                                                                          ║
║                                                                          ║
║                                                                          ║
║                                                                          ║
║                                                                          ║
║                                                                          ║
║                                                                          ║
║                                                                          ║
║                                                                          ║
║                                                                          ║
╠══════════════════════════════════════════════════════════════════════════╣
║                           ┌──────────┐  ┌──────────┐                    ║
║                           │  Cancel  │  │    OK    │                    ║
║                           └──────────┘  └──────────┘                    ║
╚══════════════════════════════════════════════════════════════════════════╝

Modal Variants

Warning Modal

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░┌────────────────────────────────┐░░░░░░░░
░░░░░░░░│ ⚠ Warning                   │✕│░░░░░░░░
░░░░░░░░├────────────────────────────────┤░░░░░░░░
░░░░░░░░│                                │░░░░░░░░
░░░░░░░░│ This action cannot be undone.  │░░░░░░░░
░░░░░░░░│ Are you sure you want to       │░░░░░░░░
░░░░░░░░│ continue?                      │░░░░░░░░
░░░░░░░░├────────────────────────────────┤░░░░░░░░
░░░░░░░░│  ┌─────────┐  ┌─────────────┐  │░░░░░░░░
░░░░░░░░│  │ Cancel  │  │   Delete    │  │░░░░░░░░
░░░░░░░░│  └─────────┘  └─────────────┘  │░░░░░░░░
░░░░░░░░└────────────────────────────────┘░░░░░░░░

Error Modal

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░┌────────────────────────────────┐░░░░░░░░
░░░░░░░░│ ✗ Error                     │✕│░░░░░░░░
░░░░░░░░├────────────────────────────────┤░░░░░░░░
░░░░░░░░│                                │░░░░░░░░
░░░░░░░░│ An error occurred while        │░░░░░░░░
░░░░░░░░│ processing your request.       │░░░░░░░░
░░░░░░░░│ Please try again later.        │░░░░░░░░
░░░░░░░░├────────────────────────────────┤░░░░░░░░
░░░░░░░░│           ┌─────────────┐      │░░░░░░░░
░░░░░░░░│           │     OK      │      │░░░░░░░░
░░░░░░░░│           └─────────────┘      │░░░░░░░░
░░░░░░░░└────────────────────────────────┘░░░░░░░░

Success Modal

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░┌────────────────────────────────┐░░░░░░░░
░░░░░░░░│ ✓ Success                   │✕│░░░░░░░░
░░░░░░░░├────────────────────────────────┤░░░░░░░░
░░░░░░░░│                                │░░░░░░░░
░░░░░░░░│ Your changes have been saved   │░░░░░░░░
░░░░░░░░│ successfully!                  │░░░░░░░░
░░░░░░░░│                                │░░░░░░░░
░░░░░░░░├────────────────────────────────┤░░░░░░░░
░░░░░░░░│           ┌─────────────┐      │░░░░░░░░
░░░░░░░░│           │   Continue  │      │░░░░░░░░
░░░░░░░░│           └─────────────┘      │░░░░░░░░
░░░░░░░░└────────────────────────────────┘░░░░░░░░

Modal Without Backdrop

┌────────────────────────────────┐
│ {{title}}                   │✕│
├────────────────────────────────┤
│                                │
│ {{content}}                    │
│                                │
│                                │
├────────────────────────────────┤
│  ┌─────────┐  ┌─────────────┐  │
│  │ Cancel  │  │   Confirm   │  │
│  └─────────┘  └─────────────┘  │
└────────────────────────────────┘

Modal with Custom Content

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░┌────────────────────────────────┐░░░░░░░░
░░░░░░░░│ Image Gallery               │✕│░░░░░░░░
░░░░░░░░├────────────────────────────────┤░░░░░░░░
░░░░░░░░│                                │░░░░░░░░
░░░░░░░░│ ┌────────────────────────────┐ │░░░░░░░░
░░░░░░░░│ │        IMAGE_CONTENT       │ │░░░░░░░░
░░░░░░░░│ │         [PHOTO]            │ │░░░░░░░░
░░░░░░░░│ │                            │ │░░░░░░░░
░░░░░░░░│ └────────────────────────────┘ │░░░░░░░░
░░░░░░░░│                                │░░░░░░░░
░░░░░░░░│ Photo 1 of 5                   │░░░░░░░░
░░░░░░░░├────────────────────────────────┤░░░░░░░░
░░░░░░░░│ ┌─────┐ ┌─────┐ ┌─────────────┐│░░░░░░░░
░░░░░░░░│ │ Prev│ │Next │ │    Close    ││░░░░░░░░
░░░░░░░░│ └─────┘ └─────┘ └─────────────┘│░░░░░░░░
░░░░░░░░└────────────────────────────────┘░░░░░░░░

Dimensions

• Small: 30×15 characters
• Medium: 50×20 characters (default)
• Large: 70×30 characters
• Fullscreen: Full viewport dimensions
• Custom: Configurable width/height

Variables

• title (string): Modal header title (max 60 characters)
• content (string, required): Main modal content (max 500 characters)
• size (string): Modal size ("small", "medium", "large", "fullscreen")
• buttons (array): Action buttons with text, variant, and action
• showCloseButton (boolean): Show X button in header (default: true)
• backdrop (boolean): Show backdrop overlay (default: true)
• variant (string): Style variant ("default", "warning", "error", "success", "info")

Accessibility

• Role: dialog
• Focus Management:
  • Trap focus within modal
  • Return focus to trigger element on close
  • Initial focus on first button or specified element
• Keyboard Support:
  • Escape: Close modal (if closable)
  • Tab/Shift+Tab: Navigate within modal
  • Enter: Activate focused button
• ARIA:
  • aria-labelledby: References title element
  • aria-describedby: References content element
  • aria-modal: "true"
  • aria-hidden: "true" on background content when modal open

Usage Examples

Confirmation Dialog

░░░░░░░░┌──────────────────────────┐░░░░░
░░░░░░░░│ Delete Item           │✕│░░░░░
░░░░░░░░├──────────────────────────┤░░░░░
░░░░░░░░│                          │░░░░░
░░░░░░░░│ Are you sure you want to │░░░░░
░░░░░░░░│ delete this item? This   │░░░░░
░░░░░░░░│ action cannot be undone. │░░░░░
░░░░░░░░├──────────────────────────┤░░░░░
░░░░░░░░│ ┌──────┐  ┌────────────┐ │░░░░░
░░░░░░░░│ │Cancel│  │   Delete   │ │░░░░░
░░░░░░░░│ └──────┘  └────────────┘ │░░░░░
░░░░░░░░└──────────────────────────┘░░░░░

Loading Modal

░░░░░░░░┌──────────────────────────┐░░░░░
░░░░░░░░│ Processing...         │░│░░░░░
░░░░░░░░├──────────────────────────┤░░░░░
░░░░░░░░│                          │░░░░░
░░░░░░░░│ Please wait while we     │░░░░░
░░░░░░░░│ process your request...  │░░░░░
░░░░░░░░│                          │░░░░░
░░░░░░░░│ ████████████████░░░░ 80% │░░░░░
░░░░░░░░└──────────────────────────┘░░░░░

Settings Modal

░░░░░░░░┌──────────────────────────────────┐░░░░░░░░
░░░░░░░░│ Preferences                   │✕│░░░░░░░░
░░░░░░░░├──────────────────────────────────┤░░░░░░░░
░░░░░░░░│                                  │░░░░░░░░
░░░░░░░░│ ☑ Enable notifications          │░░░░░░░░
░░░░░░░░│ ☐ Auto-save changes             │░░░░░░░░
░░░░░░░░│ ☑ Dark mode                     │░░░░░░░░
░░░░░░░░│                                  │░░░░░░░░
░░░░░░░░│ Language: ┌───────────────────┐  │░░░░░░░░
░░░░░░░░│           │ English          ▼│  │░░░░░░░░
░░░░░░░░│           └───────────────────┘  │░░░░░░░░
░░░░░░░░├──────────────────────────────────┤░░░░░░░░
░░░░░░░░│  ┌─────────┐  ┌─────────────────┐│░░░░░░░░
░░░░░░░░│  │ Cancel  │  │      Save       ││░░░░░░░░
░░░░░░░░│  └─────────┘  └─────────────────┘│░░░░░░░░
░░░░░░░░└──────────────────────────────────┘░░░░░░░░

Component Behavior

Modal Lifecycle

1. Trigger: User action opens modal
2. Opening: Modal animates into view
3. Open: Modal fully visible and interactive
4. Interaction: User interacts with modal content
5. Closing: Modal closes via button, escape, or backdrop
6. Closed: Modal hidden, focus restored

Focus Management

• Focus Trap: Tab navigation stays within modal
• Initial Focus: First focusable element (usually close button)
• Focus Restoration: Return to trigger element on close
• Focus Indicators: Clear visual feedback for keyboard users

Backdrop Behavior

• Backdrop Click: Close modal if backdropClosable is true
• Backdrop Scroll: Prevent page scrolling when modal open
• Multiple Modals: Handle stacking and z-index management

Design Tokens

Visual Elements

• ░ = Backdrop overlay (semi-transparent)
• ┌─┐└┘─│ = Modal border and dividers
• ╔═╗╚╝═║ = Fullscreen modal borders
• ✕ = Close button icon
• ⚠✗✓ = Status icons for variants

Spacing

• Padding: 2-3 characters internal spacing
• Margins: Centered positioning with backdrop
• Button Spacing: 2-3 characters between buttons
• Content Spacing: 1-2 lines between sections

Related Components

• Popup: Smaller, contextual overlays
• Tooltip: Informational overlays
• Dropdown: Menu-style overlays
• Sidebar: Panel-style content areas

Implementation Notes

This ASCII representation demonstrates modal overlay patterns. When implementing:

1. Focus Management: Robust focus trapping and restoration
2. Backdrop Management: Proper event handling and scroll prevention
3. Animation: Smooth open/close transitions
4. Mobile Adaptation: Responsive sizing and touch interactions
5. Performance: Efficient rendering and memory management
6. Accessibility: Full screen reader and keyboard support

Variants

• Alert Dialog: Simple message with OK button
• Confirmation Dialog: Yes/No or Cancel/Confirm actions
• Form Modal: Data input and submission
• Content Modal: Rich content display (images, videos, etc.)
• Loading Modal: Progress indication during operations