@decantr/content 3.8.0

package/patterns/form.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "id": "form",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Form",
+  "description": "Structured form with labeled field groups, validation states, and action buttons",
+  "dependencies": {
+    "patterns": {},
+    "styles": {},
+    "requires_core": {
+      "components": [
+        "Card",
+        "Input",
+        "Select",
+        "Switch",
+        "Checkbox",
+        "Button",
+        "Label",
+        "Textarea",
+        "RadioGroup"
+      ],
+      "charts": []
+    }
+  },
+  "components": [
+    "Card",
+    "Input",
+    "Select",
+    "Switch",
+    "Checkbox",
+    "Button",
+    "Label",
+    "Textarea",
+    "RadioGroup"
+  ],
+  "default_preset": "settings",
+  "presets": {
+    "settings": {
+      "description": "Vertical stack of sections, each with a title/description on the left and form fields on the right (2-column layout per section). Save button at bottom.",
+      "components": [
+        "Card",
+        "Input",
+        "Select",
+        "Switch",
+        "Button",
+        "Label",
+        "Textarea"
+      ],
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap6 _p4",
+        "slots": {
+          "section": "Card with 2-column layout: labels left, fields right",
+          "section-title": "Section heading with _heading4 and description with _bodysm _fgmuted",
+          "field-group": "Grid of form fields with _grid _gc1 _lg:gc2 _gap4",
+          "actions": "Bottom-aligned save/cancel buttons"
+        }
+      }
+    },
+    "creation": {
+      "description": "Single-column wizard-like form with sections as steps. Progress indicator at top, prev/next buttons.",
+      "components": [
+        "Card",
+        "Input",
+        "Select",
+        "Checkbox",
+        "Button",
+        "Label",
+        "Textarea"
+      ],
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap6 _p4 _mw[640px] _mx[auto]",
+        "slots": {
+          "progress": "Step indicator bar at top showing current/total steps",
+          "step-card": "Single Card containing current step fields",
+          "step-title": "Step heading with _heading4",
+          "field-group": "Vertical stack of form fields with _flex _col _gap4",
+          "navigation": "Prev/Next buttons at bottom"
+        }
+      }
+    },
+    "structured": {
+      "description": "Dense form with fieldsets, collapsible sections, and inline validation. Good for complex data entry.",
+      "components": [
+        "Card",
+        "Input",
+        "Select",
+        "Checkbox",
+        "RadioGroup",
+        "Button",
+        "Label",
+        "Textarea"
+      ],
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap4 _p4",
+        "slots": {
+          "fieldset": "Collapsible Card section with border and legend-style title",
+          "field-row": "Horizontal field groups with _grid _gc2 _gap4 for dense layout",
+          "inline-validation": "Error text below fields with _textsm _fgdestructive",
+          "actions": "Button group with save, cancel, reset"
+        }
+      }
+    }
+  },
+  "visual_brief": "Well-organized form with clear field grouping under section headings. Each section has a heading in heading4 weight and a muted description line, followed by form fields arranged in a one- or two-column grid. Labels sit above their respective fields (stacked, never side-by-side) in small medium-weight text. Input fields use consistent height (~40px), rounded corners (r2), and border styling that brightens on focus with a primary-color ring. Select dropdowns match input styling with a custom chevron. Textareas have a taller minimum height (6rem). Required fields show a small asterisk. Validation errors display below the field in small destructive-red text. The form is constrained to 640px max-width for readability. Action buttons (Save, Cancel) sit at the bottom right, separated by a top border or spacing from the form fields.",
+  "responsive": {
+    "mobile": "Single column for all field groups. Fields go full-width. Action buttons stack vertically at full width, primary on top. Section headings go full-width above fields. Padding reduces to p3.",
+    "tablet": "Two-column field grid activates for shorter fields (name, email). Textareas span full width. Action buttons stay horizontal, right-aligned.",
+    "desktop": "Full two-column grid for field groups. Settings preset shows section label column on the left, fields on the right. Generous p4 spacing. Inline validation visible without layout shift."
+  },
+  "motion": {
+    "micro": {
+      "field-focus": "border-color transition 150ms ease-out",
+      "button-press": "scale(0.97) 100ms ease-out",
+      "error-shake": "translateX(-4px, 4px, -2px, 2px, 0) 300ms ease-out on validation error"
+    },
+    "transitions": {
+      "validation-error": "fade + slideDown 200ms ease-out for error message",
+      "success-submit": "fade-out form + fade-in success message 300ms ease-out"
+    }
+  },
+  "interactions": [
+    "animate-on-mount",
+    "inline-edit",
+    "keyboard-navigation"
+  ],
+  "accessibility": {
+    "role": "form",
+    "aria-label": "Form",
+    "keyboard": [
+      "Tab navigates between fields",
+      "Shift+Tab navigates backwards between fields",
+      "Enter submits when focus is on submit button",
+      "Escape cancels or closes modal forms",
+      "Arrow keys navigate within radio groups",
+      "Space toggles checkboxes and switches"
+    ],
+    "announcements": [
+      "Validation errors announced on field blur",
+      "Required field indicator announced on focus",
+      "Success confirmation announced on submit",
+      "Field group label announced on section entry"
+    ],
+    "focus_management": "First invalid field receives focus on failed validation. On successful submit, focus moves to success message or next logical action.",
+    "labels": "Every input has an associated <label> element with matching htmlFor/id. Labels are always visible — no placeholder-only fields.",
+    "validation": "Error messages are linked to inputs via aria-describedby. Invalid fields use aria-invalid='true'. Error text uses role='alert' for screen reader announcement."
+  },
+  "layout_hints": {
+    "label_position": "stacked",
+    "note": "Labels go ABOVE their field, not side-by-side. This prevents the label-field gap problem at wide viewports.",
+    "max_width": "Form content should be constrained to max-width: 40rem (640px). Full-width forms are hard to read.",
+    "section_grouping": "Group related fields under section headers. Use a SINGLE d-surface card for the entire form, OR no card at all. Do NOT wrap each section in its own separate card.",
+    "icon_placement": "Section header icons render INLINE with the heading text (icon left of heading, vertically centered), not floating outside the card border.",
+    "select_styling": "Apply d-control to ALL form elements including <select>. Add appearance: none and a custom SVG chevron for consistent styling.",
+    "textarea": "Textareas should have min-height: 6rem to visually differentiate from single-line inputs."
+  },
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_flex _col _gap6 _p4",
+    "slots": {
+      "section": "Card with labeled field groups",
+      "section-title": "Section heading with description",
+      "field-group": "Grid of form fields",
+      "actions": "Save/cancel buttons"
+    }
+  },
+  "io": {
+    "consumes": [
+      "data"
+    ],
+    "produces": [
+      "form-data"
+    ],
+    "actions": [
+      "save",
+      "cancel",
+      "reset"
+    ]
+  },
+  "composition": {
+    "Form": "Container(d-section, flex-col, gap-6, max-width) > [FormSection[] + ActionButtons]",
+    "FormSection": "Card(d-surface) > [SectionTitle(heading4) + SectionDescription?(text-muted) + FieldGroup(d-control, grid: 1/2-col)]",
+    "FieldGroup": "Grid > Field[]",
+    "Field": "Stack(flex-col) > [Label(d-control, font-medium) + Input(d-control) + ValidationError?(d-annotation, text-destructive)]",
+    "ActionButtons": "Row(d-interactive, gap-2) > [SaveButton(variant: primary) + CancelButton(variant: ghost)]"
+  }
+}

package/patterns/founder-comic-strip.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "id": "founder-comic-strip",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Founder Comic Strip",
+  "description": "Campaign story section rendered as bold comic/manual panels for maker origin, product problem, prototype breakthrough, and launch ask.",
+  "category": "campaign",
+  "tags": [
+    "campaign",
+    "story",
+    "founder",
+    "comic",
+    "launch",
+    "trust"
+  ],
+  "components": [
+    "Media",
+    "Badge",
+    "Button",
+    "icon"
+  ],
+  "contained": false,
+  "default_preset": "story-panels",
+  "presets": {
+    "story-panels": {
+      "description": "Four to six comic-style story panels with captions, maker photos or illustrations, and a clear campaign ask.",
+      "components": [
+        "Media",
+        "Badge",
+        "Button",
+        "icon"
+      ],
+      "layout": {
+        "layout": "grid",
+        "atoms": "_grid _gap5 _wfull _maxw[76rem] _mx[auto]",
+        "slots": {
+          "story-panel": "Repeating panel with image/diagram, label, title, and short caption.",
+          "maker-note": "Plain-spoken founder note or quote.",
+          "campaign-ask": "What support enables next, with CTA."
+        }
+      }
+    },
+    "manual-origin": {
+      "description": "Instruction-manual origin story with numbered product development steps and maker credibility notes.",
+      "components": [
+        "Media",
+        "Badge",
+        "Button"
+      ],
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap5 _wfull _maxw[58rem] _mx[auto]",
+        "slots": {
+          "origin-step": "Numbered development milestone.",
+          "maker-proof": "Credentials, prototype count, customer quotes, or build progress.",
+          "campaign-ask": "Support request."
+        }
+      }
+    }
+  },
+  "default_layout": {
+    "layout": "grid",
+    "atoms": "_grid _gap5 _wfull _maxw[76rem] _mx[auto]",
+    "slots": {
+      "story-panel": "Comic-style story panel",
+      "maker-note": "Founder or team note",
+      "campaign-ask": "Support request and CTA"
+    }
+  },
+  "visual_brief": "A founder story told through bold panels rather than a wall of prose. Each panel should have a clear scene: problem, prototype, user signal, and what backing unlocks. Use photos, product sketches, UI screenshots, or simple diagrams where possible. The style should be playful but honest; campaign trust matters.",
+  "responsive": {
+    "mobile": "Single-column comic strip. Keep captions short and readable.",
+    "tablet": "Two-column panel grid with maker note spanning full width.",
+    "desktop": "Editorial comic strip or staggered grid. Avoid nested panel groups."
+  },
+  "layout_hints": {
+    "story_arc": "Problem -> prototype -> proof -> launch ask.",
+    "honesty": "Do not overclaim. Include current product state and what funding/support enables.",
+    "media": "Prefer actual maker/product evidence over decorative illustration."
+  },
+  "motion": {
+    "micro": {
+      "panel-hover": "panel shadow shifts hard by 2px; no soft elevation",
+      "caption-reveal": "caption line appears with short snap-in"
+    },
+    "transitions": {
+      "story-stagger": "Panels enter one by one as the reader scrolls."
+    }
+  },
+  "interactions": [
+    "animate-on-mount",
+    "stagger-children",
+    "hover-reveal",
+    "click-select"
+  ],
+  "composition": {
+    "FounderComicStrip": "Section > [Header + StoryPanel[] + MakerNote + CampaignAsk]",
+    "StoryPanel": "Panel(arcade-pixel-border) > [Media + PanelLabel + Title + Caption]",
+    "CampaignAsk": "ManualPanel > [AskCopy + PrimaryAction]"
+  },
+  "accessibility": {
+    "role": "region",
+    "aria-label": "Founder story",
+    "keyboard": [
+      "Interactive story panels should expose detail buttons when expandable.",
+      "Panel order must match visual reading order."
+    ],
+    "announcements": [
+      "Story panel expanded: {title}."
+    ]
+  },
+  "io": {
+    "consumes": [
+      "founder-story",
+      "prototype-evidence"
+    ],
+    "produces": [
+      "trust-signal"
+    ],
+    "actions": [
+      "story-detail-open",
+      "campaign-ask-click"
+    ]
+  }
+}

package/patterns/generative-card-grid.json

@@ -0,0 +1,130 @@
+{
+  "id": "generative-card-grid",
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Generative Card Grid",
+  "description": "A grid of cards where each card shows a procedurally generated preview of what an AI would build from a given prompt. Cards display live micro-renders, placeholder sketches, or wireframe thumbnails that materialize from skeleton states. The grid itself is generative: card sizes, positions, and visual weights adapt to content relevance and user interaction history. For AI generation galleries, prompt exploration interfaces, template browsers, and any context where users browse and compare multiple AI outputs.",
+  "category": "generative",
+  "tags": [
+    "2026",
+    "generative",
+    "cards",
+    "grid",
+    "AI",
+    "gallery",
+    "preview",
+    "masonry",
+    "prompt"
+  ],
+  "components": [
+    "PreviewCard",
+    "GenerationBadge",
+    "PromptTag",
+    "ActionBar",
+    "SkeletonPreview",
+    "RegenerateButton"
+  ],
+  "default_preset": "masonry",
+  "presets": {
+    "masonry": {
+      "description": "Variable-height masonry grid using CSS columns or grid with masonry alignment. Cards size to their content preview height. Optimal for browsing diverse generation outputs where previews have different aspect ratios. Gap between cards is consistent. New cards append with fade-in animation.",
+      "layout": {
+        "layout": "grid",
+        "atoms": "_grid _gap4 _p4"
+      }
+    },
+    "uniform": {
+      "description": "Fixed-size card grid using auto-fill with minmax(280px, 1fr). All cards same height with preview area cropped to fit. Clean and predictable. Good for structured browsing when previews have similar content types.",
+      "layout": {
+        "layout": "grid",
+        "atoms": "_grid _gap4 _p4"
+      }
+    },
+    "featured": {
+      "description": "Mixed grid where one card is expanded to 2x2 size (the featured or highest-confidence result) while others remain standard. Featured card shows larger preview with more detail. Grid rearranges when a different card is featured. Good for highlighting the best AI output.",
+      "layout": {
+        "layout": "grid",
+        "atoms": "_grid _gap4 _p4"
+      }
+    },
+    "list": {
+      "description": "Vertical list layout. Each card is a horizontal row: preview thumbnail on the left, prompt and metadata on the right, action bar at the far right. Compact and scannable. Good for comparing many generations by prompt text.",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap3 _p4"
+      }
+    }
+  },
+  "visual_brief": "Responsive auto-fill card grid (minmax 280px). Each card shows a generated preview thumbnail, a generation badge overlay (top-right), a truncated prompt label below, and a hover-reveal action bar. Cards shimmer from skeleton to final preview. Masonry or uniform sizing depending on preset.",
+  "layout_hints": {
+    "filtering": "If filter tabs or category pills are shown, they MUST be functional. Clicking a tab/pill filters the grid. Use React state to filter. Non-functional filter UI is worse than no filters.",
+    "empty_state": "When filters produce 0 results, show an empty state: centered icon (48px, muted) + descriptive message + 'Clear filters' action.",
+    "grid": "Use CSS grid with auto-fill: grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)). Cards should be equal height within each row."
+  },
+  "default_layout": {
+    "layout": "grid",
+    "atoms": "_grid _gap4 _p4",
+    "slots": {
+      "grid-container": "The grid parent that holds all preview cards. Supports auto-fill columns with responsive minmax sizing. In masonry preset, uses CSS columns or masonry grid alignment. Container handles empty state (no generations yet) with a centered prompt-to-start message. Supports infinite scroll or paginated loading.",
+      "preview-card": "Individual PreviewCard containing a generated preview. Card lifecycle: SkeletonPreview (loading) → generation animation (materializing) → final preview (interactive). Preview area shows a miniature render of the AI output: could be a wireframe, screenshot thumbnail, or abstract representation. Card has a subtle border, rounded corners, and lift shadow on hover.",
+      "generation-overlay": "GenerationBadge overlay on each card showing generation metadata: model used, generation time, confidence score, or iteration number. Positioned as a small pill in the card's top-right corner. Semi-transparent background to not obscure the preview. Shows 'Generating...' with a spinner animation during active generation.",
+      "prompt-label": "PromptTag showing the input prompt or description that produced this generation. Truncated to 2 lines with full text in a tooltip. Displayed below the preview area. Supports click-to-copy for prompt reuse. If the card represents a variation, shows the delta from the original prompt.",
+      "action-bar": "ActionBar with card-level actions: RegenerateButton (re-run this prompt), favorite/bookmark, expand to full view, copy output, delete, and share. Appears on card hover or focus. In list preset, always visible. Actions are icon-only with tooltips, except RegenerateButton which has a label.",
+      "skeleton-state": "SkeletonPreview rendered while the generation is in progress. Shows animated placeholder shapes that hint at the expected output structure: header bars, content blocks, image placeholders. Skeleton uses shimmer animation (background gradient translateX). Transitions to the real preview with a reveal animation (clip-path or opacity)."
+    }
+  },
+  "accessibility": {
+    "role": "feed",
+    "aria_label": "AI generation gallery",
+    "announcements": [
+      "Announce new generation completion: 'Generation complete: [prompt summary]'",
+      "Announce when entering skeleton/loading state: 'Generating preview for: [prompt]'",
+      "Announce grid layout changes: 'Switched to [preset] view'",
+      "Announce featured card change: '[prompt] featured'"
+    ],
+    "keyboard": [
+      "Tab navigates between cards in grid order",
+      "Arrow keys navigate between cards in 2D grid (Left/Right within row, Up/Down between rows)",
+      "Enter expands the focused card to full view",
+      "R key triggers regeneration for the focused card",
+      "F key toggles the focused card as featured",
+      "V key cycles between grid presets (masonry, uniform, featured, list)",
+      "Escape closes expanded view and returns focus to the card"
+    ],
+    "reduce_motion": "Skeleton shimmer animation replaced with static gray placeholder. Card appearance transitions are instant (no fade-in). Grid rearrangement on featured change is immediate. Generation overlay spinner replaced with static 'Generating...' text."
+  },
+  "responsive": {
+    "mobile": "Single column layout regardless of preset. Cards full-width. Preview area maintains 16:9 aspect ratio. ActionBar always visible (no hover state on touch). Skeleton state simplified to a single pulsing block. Maximum 10 cards before 'Load more' button.",
+    "tablet": "Two-column grid for uniform and masonry presets. Featured preset uses 2-column with featured card spanning full width at top. List preset unchanged. Touch targets for ActionBar buttons are 44px minimum."
+  },
+  "motion": {
+    "micro": {
+      "card-hover": "translateY(-4px) + shadow-lg 200ms ease-out",
+      "card-press": "scale(0.98) 100ms ease-out"
+    },
+    "transitions": {
+      "card-enter": "fade-up + scale(0.95→1) 300ms ease-out, stagger 50ms per card",
+      "grid-reflow": "position + size lerp 400ms ease-in-out",
+      "card-remove": "scale(1→0.9) + fade-out 200ms ease-in"
+    },
+    "ambient": {
+      "shimmer-loading": "gradient-sweep left-to-right 1.5s ease-in-out infinite on skeleton"
+    }
+  },
+  "interactions": [
+    "lift-hover",
+    "click-select",
+    "animate-on-mount",
+    "stagger-children",
+    "glow-hover",
+    "live-simulation"
+  ],
+  "composition": {
+    "GenerativeCardGrid": "Grid(d-section, auto-fill, responsive) > [PreviewCard[] + EmptyState?]",
+    "PreviewCard": "Card(d-surface, hoverable, lift-on-hover) > [SkeletonPreview | Preview + GenerationBadge(d-annotation, top-right) + PromptTag(d-data, line-clamp-2) + ActionBar]",
+    "SkeletonPreview": "Placeholder(shimmer, animated)",
+    "GenerationBadge": "Badge(d-annotation, semi-transparent) > [ModelName + GenerationTime + ConfidenceScore?]",
+    "ActionBar": "Row(d-interactive, show-on-hover) > [RegenerateButton(labeled) + FavoriteButton + ExpandButton + CopyButton + DeleteButton]"
+  }
+}

package/patterns/gesture-control-overlay.json

@@ -0,0 +1,134 @@
+{
+  "id": "gesture-control-overlay",
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Gesture Control Overlay",
+  "description": "Visual guide showing available touch and gesture controls as an animated overlay — supports step-by-step tutorial, subtle contextual hints, and full gesture reference grid.",
+  "category": "spatial",
+  "tags": [
+    "2027",
+    "frontier",
+    "spatial",
+    "gesture",
+    "touch",
+    "tutorial",
+    "onboarding",
+    "overlay",
+    "accessibility"
+  ],
+  "components": [
+    "GestureOverlay",
+    "GestureIcon",
+    "GestureLabel",
+    "HandAnimation",
+    "DismissButton",
+    "ProgressDots"
+  ],
+  "default_preset": "tutorial",
+  "presets": {
+    "tutorial": {
+      "description": "Step-by-step guided walkthrough showing one gesture at a time with animated hand demonstration, description text, and Next/Skip navigation for onboarding flows",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_fixed _inset-0 _flex _items-center _justify-center _bg-black/60 _backdrop-blur-sm _z-50"
+      }
+    },
+    "hint": {
+      "description": "Subtle ghost icons positioned near interactive elements that demonstrate the available gesture — auto-fades after 3 seconds, reappears on long-press or idle, minimal visual disruption",
+      "layout": {
+        "layout": "spatial",
+        "atoms": "_absolute _inset-0 _pointer-events-none _z-40"
+      }
+    },
+    "full": {
+      "description": "Complete gesture reference grid showing all available gestures simultaneously in a card layout — useful as a help screen or settings reference accessible via a help button",
+      "layout": {
+        "layout": "grid",
+        "atoms": "_fixed _inset-0 _flex _items-center _justify-center _bg-black/60 _backdrop-blur-sm _z-50"
+      }
+    }
+  },
+  "visual_brief": "In tutorial mode: a full-screen dark overlay (bg-black/60%, backdrop-blur-sm) with a centered content card (max-w-sm, bg-surface, rounded-2xl, shadow-2xl, overflow-hidden). The card is vertically stacked. At the top (60% of card height, bg-muted/5%): a large animated hand SVG (120px) demonstrating the current gesture. The hand is a simplified line-art illustration (stroke-width: 2, stroke: var(--d-foreground), fill: none) showing fingers in the appropriate position. The animation loops continuously: for a pinch gesture, two fingers come together over 1s then separate over 0.5s then pause 0.5s before repeating; for a swipe, a single finger moves horizontally 80px over 0.8s, pauses, then resets; for rotate, two fingers rotate 45deg clockwise over 1s then back; for tap, a finger presses down (scale 0.9) and releases (scale 1) with a ripple circle expanding from the tap point. Below the animation area: a title (text-lg, font-semibold, text-center, px-4, pt-3) like 'Pinch to Zoom', a description (text-sm, text-muted, text-center, px-4, pb-4) like 'Use two fingers to zoom in and out of the canvas'. At the bottom of the card: a footer bar (px-4, py-3, border-t, flex, justify-between, items-center). Left side: a 'Skip' text button (text-sm, text-muted). Center: ProgressDots showing tutorial position. Right side: a 'Next' button (bg-accent, text-accent-foreground, rounded-lg, px-4, py-2, text-sm, font-medium). On the last step, 'Next' changes to 'Done'. Navigating between steps crossfades the hand animation and text (200ms). In hint mode: small ghost icons (32px, opacity 0.4) appear positioned near relevant interactive elements. Each icon shows a simplified gesture symbol (e.g., two-finger spread icon near zoomable areas, swipe arrow near scrollable areas). Icons fade in over 300ms, hold for 3 seconds, then fade out over 500ms. They reappear when the user is idle for 5s or long-presses the area. Icons are pointer-events: none so they don't interfere with actual gestures. In full mode: a centered panel (max-w-lg, max-h-[80vh], bg-surface, rounded-2xl, shadow-2xl, overflow-y-auto) containing a grid (2 columns, gap-4, p-6) of gesture cards. Each card (rounded-lg, border, p-4) contains: the hand animation (64px, centered), the gesture name (text-sm, font-semibold, text-center, mt-2), and the description (text-xs, text-muted, text-center). A header bar at the top of the panel reads 'Gesture Controls' (text-lg, font-semibold) with a close X button on the right. A DismissButton (absolute, top-right of overlay, or inside panel header) closes the overlay.",
+  "layout_hints": {
+    "container": "fixed overlay (tutorial/full) or absolute overlay within a spatial container (hint)",
+    "note": "Tutorial and full presets use fixed positioning and should trap focus. Hint preset uses absolute positioning relative to a parent container and should NOT trap focus or block interactions.",
+    "gesture_library": "Common gestures to support: tap, double-tap, long-press, swipe (4 directions), pinch-to-zoom, two-finger-rotate, two-finger-scroll, three-finger-swipe. Each gesture has a unique hand animation SVG.",
+    "auto_dismiss": "Hint mode gestures auto-dismiss after 3s. Tutorial mode stays until user explicitly navigates. Full mode stays until dismissed.",
+    "first_use": "Track gesture tutorial completion in localStorage. Show tutorial automatically on first use, then only via explicit trigger (help button or keyboard shortcut)."
+  },
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_fixed _inset-0 _flex _items-center _justify-center _bg-black/60 _backdrop-blur-sm _z-50",
+    "slots": {
+      "gesture-overlay": "The full-screen backdrop layer for tutorial and full modes. Position: fixed, inset: 0. Background: black at 60% opacity with backdrop-filter: blur(4px). Z-index: 50. Clicking the backdrop area (outside the content card) dismisses the overlay in full mode but NOT in tutorial mode (to prevent accidental dismissal during onboarding). The overlay fades in (opacity 0→1 over 200ms) on open. In hint mode, the overlay is position: absolute, inset: 0, bg: transparent, pointer-events: none — it merely serves as a positioning context for hint icons.",
+      "gesture-icon": "Repeating slot — one per gesture to be demonstrated. In tutorial mode: a large (120px) area at the top of the content card reserved for the animated hand SVG. The area has a subtle muted background (bg-muted/5%, rounded-t-2xl) to frame the animation. Only one gesture-icon is visible at a time; transitions between gestures use a crossfade (old fades out 150ms, new fades in 150ms, 50ms overlap). In hint mode: small 32px icons positioned absolutely near the relevant interactive element. Each icon is a simplified gesture symbol (not a full hand animation — just iconographic: two chevrons for pinch, arrow for swipe, tap circle for tap). Opacity: 0.4, color: var(--d-foreground). In full mode: 64px animated hand SVGs centered within each gesture grid card.",
+      "gesture-label": "The text content describing each gesture. Two parts: (1) Title — the gesture name in concise imperative form ('Pinch to Zoom', 'Swipe to Navigate', 'Tap to Select'). Text-lg, font-semibold in tutorial mode; text-sm, font-semibold in full mode grid. (2) Description — a brief explanation of what the gesture does and where it applies ('Use two fingers to zoom in and out of the canvas. Works in all spatial views.'). Text-sm, text-muted in tutorial mode; text-xs, text-muted in full mode grid. Both are text-center. In hint mode, labels are hidden — only the icon is shown (the gesture name is available as a tooltip on long-press).",
+      "hand-animation": "The core animated SVG element demonstrating each gesture. The SVG uses a viewBox of '0 0 120 120' and contains path elements forming a simplified hand outline (line-art style: stroke: var(--d-foreground), stroke-width: 2, stroke-linecap: round, fill: none). Different gesture animations: PINCH — two fingers (index + thumb) start 40px apart and move to 8px apart over 800ms ease-in-out, pause 400ms, then separate back over 600ms, pause 400ms, loop. A small circle appears at the pinch point when fingers meet. SWIPE — single finger starts at x:20 and moves to x:100 over 600ms ease-out, leaves a motion trail (5 circles of decreasing opacity behind the finger), then resets instantly to start position after 500ms pause. ROTATE — two fingers positioned 30px apart rotate 45deg clockwise around their midpoint over 1s ease-in-out, pause 400ms, rotate back, pause 400ms, loop. A curved arrow appears between the fingers indicating rotation direction. TAP — single finger in resting position, quickly scales to 0.9 (press) over 100ms then back to 1.0 over 100ms, accompanied by a ripple circle (expanding ring from tap point, 0→40px radius, opacity 1→0, 400ms). Long-press: same as tap but the press holds for 800ms with a circular progress ring filling around the finger. All animations use CSS animations or SMIL for smooth 60fps playback.",
+      "dismiss-button": "A close button to dismiss the overlay. In tutorial mode: positioned as a 'Skip' text button in the card footer (text-sm, text-muted, hover: text-foreground, cursor: pointer). Also a small X icon button (24px, absolute top-3 right-3 of the card, text-muted, hover: text-foreground) for quick dismissal. In full mode: the X button in the panel header (right-aligned, 24px, same styling) plus clicking the backdrop. In hint mode: no dismiss button — hints auto-dismiss after 3s. All dismiss actions trigger the overlay-close transition.",
+      "progress-dots": "Tutorial step indicator centered in the card footer. A horizontal row of dots (8px circles, gap-2). Current step dot: bg-accent, scale(1). Completed step dots: bg-accent at 40% opacity. Upcoming step dots: bg-muted, border 1.5px solid var(--d-border). Dots transition between states with background-color 200ms and transform 200ms. If there are more than 7 steps, dots collapse to show current + 2 on each side with ellipsis. Clicking a dot in full mode jumps to that gesture (in tutorial mode, only forward navigation via Next is allowed to ensure sequential learning)."
+    }
+  },
+  "accessibility": {
+    "role": "dialog",
+    "aria-label": "Gesture controls guide",
+    "aria-modal": "true",
+    "announcements": [
+      "Gesture tutorial opened — step {current} of {total}",
+      "Gesture: {name} — {description}",
+      "Navigated to gesture {current} of {total}: {name}",
+      "Gesture tutorial completed",
+      "Gesture guide closed"
+    ],
+    "keyboard": [
+      "Arrow Right / Enter: next gesture (tutorial mode)",
+      "Arrow Left: previous gesture (tutorial mode)",
+      "Escape: dismiss overlay",
+      "Tab: cycle through gesture cards (full mode)",
+      "Space: replay current gesture animation",
+      "?: open gesture guide from anywhere in the app"
+    ]
+  },
+  "responsive": {
+    "mobile": "Tutorial card expands to full-width (inset-x: 16px). Hand animation area remains 120px. Full mode switches from 2-column grid to single column scrollable list. Hint icons increase to 40px for visibility on touch screens. All touch targets minimum 44px. Progress dots remain at 8px.",
+    "tablet": "Tutorial card at max-w-sm centered. Full mode at 2-column grid. Hand animations at full size. Standard touch targets."
+  },
+  "motion": {
+    "micro": {
+      "next-button-hover": "bg-accent brightness increase + scale(1.02), 150ms ease-out",
+      "skip-hover": "color muted→foreground 150ms",
+      "dot-hover": "scale(1.15) 150ms"
+    },
+    "transitions": {
+      "overlay-open": "backdrop opacity 0→1 200ms, card scale(0.9)→scale(1) + opacity 0→1 250ms spring",
+      "overlay-close": "card scale(1)→scale(0.95) + opacity 1→0 150ms ease-in, backdrop opacity 1→0 200ms",
+      "step-change": "current content fade-out 150ms, new content fade-in 150ms with 50ms overlap — crossfade effect",
+      "hint-appear": "opacity 0→0.4 + scale(0.8→1) 300ms ease-out",
+      "hint-disappear": "opacity 0.4→0 500ms ease-in"
+    },
+    "ambient": {
+      "pinch-loop": "fingers approach 800ms → pause 400ms → separate 600ms → pause 400ms, infinite",
+      "swipe-loop": "finger translate 80px 600ms ease-out → pause 500ms → reset instant → pause 300ms, infinite",
+      "rotate-loop": "fingers rotate ±45deg 1s ease-in-out → pause 400ms, infinite",
+      "tap-ripple": "circle expand 0→40px + opacity 1→0 400ms ease-out per tap cycle",
+      "hint-idle-reappear": "after 5s user idle, hints fade back in at 0.3 opacity"
+    }
+  },
+  "interactions": [
+    "animate-on-mount",
+    "focus-trap",
+    "keyboard-navigation",
+    "glow-hover",
+    "live-simulation"
+  ],
+  "composition": {
+    "GestureControlOverlay": "Overlay(fixed|absolute, backdrop, z-50) > [ContentCard(d-surface, centered) + DismissButton]",
+    "ContentCard": "Surface(rounded-2xl, shadow-2xl, max-w-sm, overflow-hidden) > [AnimationArea + LabelArea + FooterBar]",
+    "AnimationArea": "Div(bg-muted/5%, flex, items-center, justify-center, h-60%) > HandAnimation(svg, animated, 120px)",
+    "LabelArea": "Div(px-4, py-3, text-center) > [GestureLabel.title(text-lg, font-semibold) + GestureLabel.description(text-sm, text-muted)]",
+    "FooterBar": "Div(flex, justify-between, items-center, px-4, py-3, border-t) > [SkipButton + ProgressDots + NextButton(d-interactive)]",
+    "HandAnimation": "SVG(viewBox: 0 0 120 120, line-art) > [FingerPaths*(stroke-animated) + EffectElements(ripple|trail|arrow)]",
+    "GestureIcon": "Div(positioned-absolute|inline, 32px|64px|120px) > SVG(gesture-symbol|hand-animation)",
+    "ProgressDots": "Flex(gap-2, items-center) > Dot*(8px, circle, state: current|completed|upcoming)"
+  }
+}