@decantr/content 3.8.0

package/patterns/timeline-scrubber.json

@@ -0,0 +1,107 @@
+{
+  "id": "timeline-scrubber",
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Timeline Scrubber",
+  "description": "Horizontal multi-track timeline with draggable scrubber handle, scene markers, keyframe dots, and zoom controls for video/audio editing workflows.",
+  "category": "media",
+  "tags": ["2026", "media", "timeline", "video", "audio", "scrubber", "editor"],
+  "components": ["TimelineCanvas", "TrackRow", "Scrubber", "KeyframeDot", "SceneMarker", "ZoomControls"],
+  "default_preset": "video",
+  "presets": {
+    "video": {
+      "description": "Multi-track video timeline with frame thumbnails, stacked audio tracks, scene markers, and full keyframe support for editing workflows",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_relative _w100 _flex _flex-col _bg-surface _border-t"
+      }
+    },
+    "audio": {
+      "description": "Audio-focused timeline rendering waveform envelopes across multiple stems with beat grid alignment and region editing",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_relative _w100 _flex _flex-col _bg-surface"
+      }
+    },
+    "simple": {
+      "description": "Single track timeline with scrubber and basic zoom, suitable for preview players and lightweight review tools",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_relative _w100 _flex _flex-col _bg-surface-muted"
+      }
+    }
+  },
+  "visual_brief": "A horizontal multi-track timeline stacked vertically with a fixed-position time ruler at top showing hours:minutes:seconds:frames tick marks. Video tracks render sequential frame thumbnails (approximately 80x45px each) at regular intervals matching zoom level. Audio tracks show symmetrical amplitude waveform envelopes in accent color against a muted background. A prominent vertical scrubber line (2px wide, primary color) spans all tracks with a triangular playhead handle at top that the user drags left-right to seek. Scene markers appear as colored flags above the ruler at scene-change timestamps, each with a 12px colored pennant shape. Keyframes render as 8px rotated-square diamond shapes on their associated track rows, connected by thin lines showing interpolation. Zoom controls sit in a small pill at bottom-right with +/-/fit buttons. Current time displays in monospace font at top-left (e.g. 00:02:14:07). Beat/frame grid lines run vertically through all tracks at zoom-appropriate density.",
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_relative _w100 _flex _flex-col _bg-surface _border-t",
+    "slots": {
+      "time-ruler": "Horizontal ruler at the top showing time markers with major ticks (seconds) and minor ticks (frames). Label format depends on zoom level: frames, seconds, or minutes. Monospace font for time labels. Scrolls horizontally in sync with track content.",
+      "track-stack": "Vertical stack of track rows. Each row is 64px tall for video tracks (to accommodate thumbnails) or 48px tall for audio tracks. Rows have a track header on the left (120px fixed) showing track name, mute/solo, and lock toggles, with the waveform/thumbnail area filling remaining width.",
+      "scrubber": "Vertical playhead line spanning all tracks, draggable via triangular handle at top. Must use pointer-events to capture drag; updates time via onChange. Shows current-time tooltip near the handle while dragging.",
+      "scene-markers": "Colored flag markers positioned absolutely above the ruler at scene-change timestamps. Hover shows scene name tooltip. Clicking jumps the scrubber to the marker position.",
+      "keyframes": "Diamond-shaped dots on individual track rows at automation keyframe timestamps. Selectable, draggable, connected by interpolation lines that reflect curve type (linear, bezier, hold).",
+      "zoom-controls": "Small pill-shaped toolbar anchored bottom-right with zoom-in, zoom-out, and fit-to-content buttons. Icon-only with tooltips."
+    }
+  },
+  "responsive": {
+    "mobile": "Track headers collapse to 48px wide icon-only. Zoom controls hidden, replaced by pinch gesture. Thumbnails downscaled to 40x22px. Scene markers render as colored dots without labels.",
+    "tablet": "Standard layout with slightly reduced track heights (52px video, 40px audio). Touch-drag for scrubber and two-finger pinch for zoom.",
+    "desktop": "Full layout with all controls visible and keyboard shortcuts enabled for playback and zoom navigation."
+  },
+  "layout_hints": {
+    "playhead_priority": "The scrubber and time ruler should be the dominant orientation anchors. Tracks, keyframes, and markers all support that shared temporal frame.",
+    "track_hierarchy": "Video, audio, and annotation tracks should remain clearly separated so the user always understands what layer they are editing or reviewing.",
+    "zoom_discipline": "As zoom changes, maintain the relationship between ruler, markers, and media blocks instead of letting one layer drift out of sync with the others."
+  },
+  "layout_hints": {
+    "playhead_priority": "The scrubber and time ruler should be the dominant orientation anchors. Tracks, keyframes, and markers all support that shared temporal frame.",
+    "track_hierarchy": "Video, audio, and annotation tracks should remain clearly separated so the user always understands what layer they are editing or reviewing.",
+    "zoom_discipline": "As zoom changes, maintain the relationship between ruler, markers, and media blocks instead of letting one layer drift out of sync with the others."
+  },
+  "motion": {
+    "micro": {
+      "scrubber-drag": "scrubber x-position follows pointer at 60fps with no easing",
+      "keyframe-hover": "scale(1.4) 120ms ease-out with glow ring"
+    },
+    "transitions": {
+      "zoom-change": "track-width transition 250ms ease-in-out with thumbnail re-rendering",
+      "marker-add": "scale(0) to scale(1) with bounce 200ms spring"
+    },
+    "ambient": {
+      "playhead-playing": "scrubber advances continuously at playback rate with subtle glow pulse"
+    }
+  },
+  "interactions": [
+    "animate-on-mount",
+    "stagger-children",
+    "real-time-updates",
+    "scroll-reveal"
+  ],
+  "composition": {
+    "TimelineScrubber": "Root(d-section, stack) > [TimeRuler + TrackStack + ZoomControls]",
+    "TrackStack": "Container > TrackRow*(d-surface) > [TrackHeader + TrackContent > (FrameThumbnails | Waveform) + KeyframeDot* + SceneMarker*]",
+    "Scrubber": "Overlay(absolute, full-height) > [ScrubberHandle(triangle) + ScrubberLine(vertical) + TimeTooltip?]",
+    "ZoomControls": "Pill(d-control, bottom-right) > [ZoomIn + ZoomOut + FitButton]"
+  },
+  "accessibility": {
+    "role": "application",
+    "aria-label": "Media timeline editor",
+    "announcements": [
+      "Playhead at {timestamp}",
+      "Scene marker {name} added at {timestamp}",
+      "Zoomed to {level}"
+    ],
+    "keyboard": [
+      "Space: play/pause",
+      "Left/Right: step one frame",
+      "Shift+Left/Right: jump 10 frames",
+      "Home: jump to start",
+      "End: jump to end",
+      "+/-: zoom in/out",
+      "M: add scene marker at playhead",
+      "K: add keyframe at playhead"
+    ]
+  }
+}

package/patterns/timeline.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "id": "timeline",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Timeline",
+  "description": "Chronological sequence of events with dates, descriptions, and optional media.",
+  "tags": [
+    "history",
+    "events",
+    "chronology",
+    "activity",
+    "milestones"
+  ],
+  "classification": {
+    "triggers": [
+      "timeline",
+      "history",
+      "milestones",
+      "event log",
+      "journey"
+    ],
+    "tier": "recommended"
+  },
+  "components": ["Card", "Badge", "icon", "Text"],
+  "default_preset": "default",
+  "presets": {
+    "default": {
+      "description": "Vertical timeline with alternating sides",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap6 _rel",
+        "slots": {
+          "events": "Vertical sequence of timeline entries alternating around a central connector line"
+        },
+        "orientation": "vertical",
+        "alternating": true
+      }
+    },
+    "compact": {
+      "description": "Single-side vertical timeline with all entries on one side of the connector line for compact layouts",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap4 _rel",
+        "slots": {
+          "events": "Compact single-sided vertical timeline entries aligned to one connector line"
+        },
+        "orientation": "vertical",
+        "alternating": false
+      }
+    },
+    "horizontal": {
+      "description": "Horizontal scrolling timeline with entries arranged left-to-right along a connector line",
+      "layout": {
+        "layout": "row",
+        "atoms": "_flex _gap6 _overauto",
+        "slots": {
+          "events": "Horizontally scrolling timeline entries arranged along a shared connector line"
+        },
+        "orientation": "horizontal"
+      }
+    }
+  },
+  "slots": {
+    "events": {
+      "type": "array",
+      "item": {
+        "date": {
+          "type": "datetime",
+          "required": true
+        },
+        "title": {
+          "type": "text",
+          "required": true
+        },
+        "description": {
+          "type": "text",
+          "required": false
+        },
+        "icon": {
+          "type": "icon",
+          "required": false
+        },
+        "media": {
+          "type": "image",
+          "required": false
+        }
+      }
+    }
+  },
+  "layout": {
+    "container": "section",
+    "header": [
+      "title?"
+    ],
+    "body": [
+      "events"
+    ],
+    "connector": "line"
+  },
+  "visual_brief": "Vertical sequence of timeline entries connected by a thin vertical line. Each entry has a small circle dot on the line, a date or timestamp label, an event title in medium weight, and a description paragraph. Optional media (images, icons) can appear beside entries. The compact preset reduces spacing and hides descriptions, showing only date and title. The horizontal preset arranges entries left-to-right along a horizontal line with dates below and content above. Milestone entries may have a larger dot or distinct icon.",
+  "layout_hints": {
+    "connector_rhythm": "The connector line should unify the sequence visually without overpowering the content. Dots and timestamps need stable alignment across entries.",
+    "milestone_emphasis": "Milestone entries may be more prominent, but they should still belong to the same temporal rhythm as the surrounding items.",
+    "content_balance": "Descriptions and optional media should support the chronology rather than turning the timeline into a card gallery."
+  },
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_flex _col _gap6 _rel",
+    "slots": {
+      "events": "Vertical sequence of timeline entries alternating around a central connector line"
+    }
+  },
+  "responsive": {
+    "mobile": "Vertical timeline only. Line on the left edge with content to the right. Dates above entries. Compact spacing.",
+    "tablet": "Standard vertical timeline with comfortable spacing. Content beside the timeline dots.",
+    "desktop": "Full vertical or horizontal timeline. Entries alternate left and right of the center line (vertical) or spread evenly (horizontal)."
+  },
+  "motion": {
+    "micro": "Connector highlights and milestone accents may animate softly on hover and focus.",
+    "transitions": "New entries or progressive reveals should fade or slide in gently without making the chronology feel unstable."
+  },
+  "interactions": [
+    "animate-on-mount",
+    "stagger-children",
+    "real-time-updates",
+    "scroll-reveal"
+  ],
+  "accessibility": {
+    "role": "list",
+    "aria-label": "Timeline",
+    "keyboard": [
+      "Tab moves through interactive timeline items and associated actions in chronological order."
+    ],
+    "announcements": [
+      "Dates, titles, and milestone states should be available semantically rather than through layout alone."
+    ],
+    "focus_management": "Keep focus transitions chronological and avoid jumping users between distant timeline entries unexpectedly."
+  }
+}

package/patterns/toast-notification.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "id": "toast-notification",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Toast Notification",
+  "description": "Transient notification toast with auto-dismiss timer, severity-colored stripe, stacking behavior, and optional action buttons. Slides in from top-right and auto-removes after a configurable duration with a shrinking progress bar.",
+  "category": "system",
+  "tags": [
+    "2026",
+    "system",
+    "notification",
+    "toast",
+    "alert",
+    "feedback",
+    "transient"
+  ],
+  "components": [
+    "ToastContainer",
+    "Toast",
+    "ToastIcon",
+    "ToastTitle",
+    "ToastDescription",
+    "ToastAction",
+    "DismissButton",
+    "ProgressBar"
+  ],
+  "default_preset": "info",
+  "presets": {
+    "info": {
+      "description": "Informational toast with blue left stripe, info circle icon, and neutral styling for general messages",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_fixed _top4 _right4 _z[200] _flex _col _gap2"
+      }
+    },
+    "success": {
+      "description": "Success toast with green left stripe, checkmark icon, confirming a completed action",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_fixed _top4 _right4 _z[200] _flex _col _gap2"
+      }
+    },
+    "warning": {
+      "description": "Warning toast with amber left stripe, triangle-exclamation icon, for non-blocking cautions",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_fixed _top4 _right4 _z[200] _flex _col _gap2"
+      }
+    },
+    "error": {
+      "description": "Error toast with red left stripe, x-circle icon, for failures requiring attention — does not auto-dismiss",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_fixed _top4 _right4 _z[200] _flex _col _gap2"
+      }
+    },
+    "action": {
+      "description": "Toast with an inline action button on the right side for undo, retry, or custom CTA alongside the message",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_fixed _top4 _right4 _z[200] _flex _col _gap2"
+      }
+    }
+  },
+  "visual_brief": "Fixed-position toast container anchored to the top-right corner of the viewport. Each toast is a compact card (max-width 380px) with border-radius 8px, a 4px left color stripe indicating severity (blue for info, green for success, amber for warning, red for error). Interior layout is a row: a 20px severity icon on the left, then a vertical stack of bold title (14px, font-weight 600) and description text (13px, muted color) in the center, and a small ghost dismiss button (X icon, 16px) on the far right. In the action preset, a small outlined button sits between the text and dismiss button. At the very bottom of each toast card, a thin 2px progress bar spans the full width, starting at 100% and shrinking to 0% over the auto-dismiss duration (default 5 seconds), colored to match the severity stripe. The bar uses a linear animation for predictable timing. Multiple toasts stack vertically with 8px gap, newest on top. When more than 3 toasts are visible, older toasts compress to show only a 4px peek of their top edge behind the stack, giving a layered card-deck appearance. Toast cards have a subtle box-shadow (0 4px 12px rgba(0,0,0,0.15)) and a 1px border in a muted tone. Background uses the standard surface color with high opacity (no frosted glass).",
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_fixed _top4 _right4 _z[200] _flex _col _gap2",
+    "slots": {
+      "toast-container": "Fixed-position wrapper anchored top-right of the viewport. Manages stacking order of multiple toasts with newest on top. Sets max-width 380px for all child toasts. Handles vertical gap and overflow behavior when more than 3 toasts are visible by compressing older toasts into a peek stack.",
+      "toast-card": "Repeating slot — one per notification. A compact card with 4px colored left border-stripe indicating severity (blue=info, green=success, amber=warning, red=error). Interior is a row layout: ToastIcon (20px severity icon matching stripe color) on the left, a vertical stack of ToastTitle (bold, 14px) and ToastDescription (muted, 13px) in the center, and DismissButton (ghost X, 16px) on the right. Card has border-radius 8px, subtle shadow, surface background, 12px padding. Error toasts have a faint red background tint.",
+      "toast-action": "Optional slot for the action preset. A small outlined button (text + optional icon) positioned between the description text and the dismiss button. Button uses accent color and ghost variant. Common actions: Undo, Retry, View, Open.",
+      "progress-bar": "A 2px-tall bar at the absolute bottom of the toast card spanning its full width. Starts at 100% width and linearly shrinks to 0% over the auto-dismiss duration. Color matches the severity stripe. When it reaches 0%, the toast dismisses. Error toasts have no progress bar (they persist until manually dismissed)."
+    }
+  },
+  "accessibility": {
+    "role": "alert",
+    "aria-label": "Notification toast",
+    "announcements": [
+      "New notification: {severity} — {title}: {description}",
+      "Notification dismissed",
+      "Action available: {action_label}",
+      "Error notification requires manual dismissal"
+    ],
+    "keyboard": [
+      "Tab: focus the toast, then cycle through action button and dismiss button",
+      "Enter: activate focused button (action or dismiss)",
+      "Escape: dismiss the currently focused toast",
+      "F6: move focus to the toast container when notifications are present"
+    ]
+  },
+  "responsive": {
+    "mobile": "Toasts appear at the top of the screen spanning full width with 8px horizontal margin. Max-width removed. Stack compresses to show only the newest toast with a count badge ('2 more') below. Swipe right to dismiss. Progress bar height increases to 3px for visibility.",
+    "tablet": "Toasts anchored top-right at 380px max-width. Standard stacking with up to 3 visible. Dismiss on tap of X button.",
+    "desktop": "Full layout with top-right positioning, hover reveals dismiss button (hidden by default on non-error toasts), mouse hover pauses the auto-dismiss timer and progress bar animation."
+  },
+  "motion": {
+    "micro": {
+      "dismiss-hover": "opacity 0.6→1 + scale(1.1) 120ms ease-out on dismiss button hover",
+      "action-press": "scale(0.96) 80ms ease-in on action button press"
+    },
+    "transitions": {
+      "toast-enter": "translateX(120%)→translateX(0) + opacity 0→1 350ms cubic-bezier(0.21, 1.02, 0.73, 1)",
+      "toast-exit": "translateX(0)→translateX(120%) + opacity 1→0 250ms ease-in",
+      "stack-reorder": "translateY shift 200ms ease-out when toasts above are dismissed",
+      "progress-shrink": "width 100%→0% linear over auto-dismiss duration"
+    },
+    "ambient": {
+      "error-pulse": "box-shadow pulse with red glow 2s ease-in-out infinite on error toasts"
+    }
+  },
+  "interactions": [
+    "animate-on-mount",
+    "stagger-children"
+  ],
+  "composition": {
+    "ToastContainer": "Container(fixed, top-right, z-200, flex-col, gap-2) > Toast*",
+    "Toast": "Card(d-surface, border-left: severity-color, shadow, max-w-380) > [ToastIcon(severity-color) + ContentStack + ToastAction?(d-interactive) + DismissButton(ghost) + ProgressBar(absolute-bottom)]",
+    "ContentStack": "Stack(flex-col, gap-1) > [ToastTitle(font-bold, text-sm) + ToastDescription(text-xs, muted)]",
+    "ProgressBar": "Bar(absolute, bottom-0, h-2px, bg: severity-color, width: 100%→0%, linear)"
+  }
+}

package/patterns/tool-list.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "id": "tool-list",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Tool List",
+  "description": "Dense two-column list of tools or features with monospace names and muted descriptions. CLI-style layout with colored dot bullets and a colored left border accent per item. Each item gets a unique color from a rotating palette. Hover highlights the row background. Pure text layout with no component dependencies.",
+  "dependencies": {
+    "patterns": {},
+    "styles": {},
+    "requires_core": {
+      "components": [],
+      "charts": []
+    }
+  },
+  "components": ["Text", "Container"],
+  "contained": false,
+  "default_preset": "standard",
+  "presets": {
+    "standard": {
+      "description": "Two-column grid of tool items with no gap between rows. Each item has: a 4px colored left border accent, a colored dot bullet (6px circle), a monospace tool name in the item's accent color, and a muted description below. Items have subtle bottom borders and a semi-transparent background that brightens on hover. Colors rotate through coral, amber, cyan, green, yellow, orange, purple, pink, crimson. Layout: 2-column grid on desktop, single column on mobile.",
+      "components": [],
+      "layout": {
+        "layout": "grid",
+        "atoms": "_grid _gc2 _gap0 _mw[880px] _mx[auto]",
+        "slots": {
+          "tool-name": "Tool name displayed in monospace font with _mono _fs[0.82rem] _fw600 _mb1. Includes a colored dot bullet (6px circle, inline-block, flex-shrink-0) before the name. Both the dot and name text use the item's accent color from the rotation palette. Wrapped in a _flex _items[center] _gap2 container.",
+          "tool-description": "Tool description with _fs[0.82rem] _fgmuted _lh[1.4]. Brief one-line description of the tool's purpose."
+        }
+      }
+    },
+    "compact": {
+      "description": "Single-column layout with denser spacing. Same colored dot bullets and monospace names, but items are stacked in a single column for narrower containers or longer lists. Reduced padding for a more compact feel.",
+      "components": [],
+      "layout": {
+        "layout": "grid",
+        "atoms": "_grid _gc1 _gap0 _mw[640px] _mx[auto]",
+        "slots": {
+          "tool-name": "Monospace tool name with colored dot bullet, _mono _fs[0.8rem] _fw600. Color from rotating palette.",
+          "tool-description": "Muted description text with _fs[0.8rem] _fgmuted _lh[1.4]."
+        }
+      }
+    }
+  },
+  "default_layout": {
+    "layout": "grid",
+    "atoms": "_grid _gc2 _gap0 _mw[880px] _mx[auto]",
+    "slots": {
+      "tool-name": "Monospace name with colored dot bullet",
+      "tool-description": "Muted description text"
+    }
+  },
+  "io": {
+    "consumes": [],
+    "produces": [],
+    "actions": []
+  },
+  "visual_brief": "Dense two-column list of tools or features. Each item shows a colored dot bullet on the left (cycling through a rotating palette), the tool name in monospace medium-weight text, and a muted description beside or below it. A thin colored left border accent matches the dot color per item. Rows highlight on hover with a subtle background tint. The compact preset reduces line height and removes descriptions, showing names only. Pure text layout with no images or icons, relying on typography and color accents for visual hierarchy.",
+  "responsive": {
+    "mobile": "Single-column list. Names and descriptions stack vertically per item. Full-width rows.",
+    "tablet": "Two-column list if items fit. Comfortable row spacing.",
+    "desktop": "Two-column grid with items distributed evenly. Hover effects visible. Full descriptions inline."
+  },
+  "layout_hints": {
+    "scan_priority": "Tool name comes first, then a short supporting description. The color dot and border are just enough to help scan, not enough to become the main content.",
+    "density": "This pattern is meant to be compact and text-forward. Keep rows tight and consistent so the list feels like a curated inventory rather than a card gallery.",
+    "column_balance": "In two-column layouts, maintain even visual weight between columns instead of letting one side become noticeably denser or longer."
+  },
+  "motion": {
+    "micro": "Rows may brighten slightly on hover and focused tool names may sharpen subtly for keyboard users.",
+    "transitions": "Filtering or list updates should preserve the sense of a stable catalog rather than reflowing with flashy animation."
+  },
+  "interactions": [
+    "click-select",
+    "hover-reveal",
+    "animate-on-mount",
+    "stagger-children"
+  ],
+  "accessibility": {
+    "role": "list",
+    "aria-label": "Tool list",
+    "keyboard": [
+      "If items are interactive, focus should move tool by tool in reading order without exposing decorative accents as separate stops."
+    ],
+    "announcements": [
+      "Tool name and description should be exposed semantically so the list remains meaningful without relying on colored bullets or borders."
+    ]
+  }
+}

package/patterns/trace-waterfall.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "id": "trace-waterfall",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Trace Waterfall",
+  "description": "Horizontal waterfall chart showing execution trace spans with nested parent-child relationships, color-coded by span type, time axis alignment, and expandable span detail panels for debugging distributed systems.",
+  "category": "observability",
+  "tags": [
+    "2026",
+    "observability",
+    "tracing",
+    "waterfall",
+    "spans",
+    "distributed-systems",
+    "performance"
+  ],
+  "components": [
+    "TraceContainer",
+    "SpanBar",
+    "SpanLabel",
+    "TimeAxis",
+    "SpanDetail",
+    "FilterBar"
+  ],
+  "default_preset": "standard",
+  "presets": {
+    "standard": {
+      "description": "Full trace waterfall with all spans expanded showing nested parent-child indentation, time axis with millisecond markers, and click-to-expand detail panels",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap0 _wfull _overflow-x-auto"
+      }
+    },
+    "compact": {
+      "description": "Collapsed spans grouped by service — only top-level spans visible by default with expand toggles to reveal children, reducing vertical space for large traces",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap0 _wfull _compact"
+      }
+    },
+    "flame": {
+      "description": "Flame chart style rendering where spans stack vertically by depth level rather than listing sequentially — wider bars represent longer durations, nested calls stack downward creating a flame shape",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap0 _wfull _overflow-x-auto _overflow-y-auto"
+      }
+    }
+  },
+  "visual_brief": "Vertical list of horizontal bars where each bar represents a trace span. A horizontal time axis runs across the top with millisecond markers and thin vertical gridlines descending the full height. Each span row contains a left-aligned label area (service name, operation name, duration text) and a horizontal bar positioned and sized proportionally to its start time and duration relative to the total trace. Nested child spans indent further right in the label column and align beneath their parent bars. Bar colors indicate span type: blue for HTTP calls, green for database queries, purple for AI/LLM calls, orange for cache operations, red for errored spans. Hovering a span highlights it with increased opacity and dims all non-ancestor/non-descendant spans. Clicking a span expands a detail panel below it showing metadata key-value pairs, tags, log entries, and timing breakdown. Error spans display a red left border and a small warning triangle icon in the label area. The filter bar at the top provides service name dropdown, minimum duration slider, and error-only toggle.",
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_flex _col _gap0 _wfull _overflow-x-auto",
+    "slots": {
+      "filter-bar": "Horizontal toolbar at the top containing a service name dropdown filter, a minimum duration threshold slider, an error-only toggle switch, and a search input for filtering spans by operation name. Filters apply instantly and fade out non-matching spans rather than removing them.",
+      "time-axis": "Fixed horizontal ruler at the top of the waterfall showing time markers in milliseconds. Thin vertical gridlines extend downward through all span rows. The axis auto-scales to fit the trace duration. Markers appear at regular intervals (e.g., every 50ms or 100ms depending on total duration). The total trace duration displays at the right edge.",
+      "span-row": "Repeating slot — one per span. Each row is a horizontal strip divided into a fixed-width label area on the left and a proportional bar area on the right. The label area shows: indent guides (thin vertical lines) for nesting depth, an expand/collapse chevron if the span has children, the service name as a colored badge, the operation name, and the duration in milliseconds. The bar area contains a colored horizontal rectangle positioned according to start time and sized according to duration. Error spans have a red-tinted background on the entire row.",
+      "span-detail": "Expandable panel that appears below a span row when clicked. Contains a metadata section with key-value pairs (trace ID, span ID, parent ID, service, operation), a tags section showing span attributes as pills, a logs section with timestamped log entries, and a timing breakdown showing queue time, execution time, and child time as a stacked mini-bar."
+    }
+  },
+  "responsive": {
+    "mobile": "Label area collapses to show only service icon and duration. Span bars use full width. Tap a span to open detail in a bottom sheet. Filter bar collapses to a single filter icon button that opens a dropdown. Time axis shows fewer markers.",
+    "tablet": "Standard layout with slightly narrower label area. Span detail opens inline. Filter bar fully visible. Comfortable touch targets on span rows.",
+    "desktop": "Full waterfall with generous label area showing service name, operation, and duration. Hover effects active. Span detail expands inline with full metadata. Filter bar shows all controls in a single row."
+  },
+  "layout_hints": {
+    "axis_priority": "The time axis and span alignment must remain visually trustworthy. Labels, bars, and detail panels should all reinforce the temporal read rather than acting like separate widgets.",
+    "detail_discipline": "Expanded span details should feel attached to their parent row and should not break the user's sense of trace hierarchy.",
+    "filter_rhythm": "Keep the filter bar compact and clearly upstream of the waterfall so it reads as a control strip, not as another data panel."
+  },
+  "motion": {
+    "micro": {
+      "span-hover": "opacity 0.7→1 + background-tint 150ms ease-out on hovered span, opacity 1→0.3 on non-related spans",
+      "bar-highlight": "box-shadow glow matching span color 200ms ease-out"
+    },
+    "transitions": {
+      "detail-expand": "max-height 0→auto + fade 250ms ease-out",
+      "detail-collapse": "max-height auto→0 + fade 150ms ease-in",
+      "filter-apply": "opacity transition 300ms ease-out on non-matching spans"
+    },
+    "ambient": {
+      "error-pulse": "border-left color pulse red 2s ease-in-out infinite on error spans"
+    }
+  },
+  "interactions": [
+    "hover-tooltip",
+    "hover-reveal",
+    "click-select",
+    "status-pulse",
+    "animate-on-mount",
+    "real-time-updates",
+    "keyboard-navigation"
+  ],
+  "composition": {
+    "TraceWaterfall": "TraceContainer(d-section, flex-col) > [FilterBar(d-control) + TimeAxis(d-annotation) + SpanList]",
+    "FilterBar": "Row(d-control) > [ServiceFilter + DurationSlider + ErrorToggle + SearchInput]",
+    "TimeAxis": "Ruler(d-annotation, sticky-top) > [TimeMarker* + Gridlines]",
+    "SpanList": "Stack(d-data) > SpanRow*",
+    "SpanRow": "Row(d-interactive, indent: depth) > [SpanLabel > [Chevron? + ServiceBadge + OperationName + Duration] + SpanBar(color: type, position: startTime, width: duration)] + SpanDetail?(d-surface)",
+    "SpanDetail": "Panel(d-surface, expandable) > [Metadata(d-data) + Tags + Logs + TimingBreakdown]"
+  },
+  "accessibility": {
+    "role": "tree",
+    "aria-label": "Execution trace waterfall showing span hierarchy",
+    "keyboard": [
+      "Arrow Up/Down: navigate between span rows",
+      "Arrow Right: expand collapsed span children or open span detail",
+      "Arrow Left: collapse expanded children or close span detail",
+      "Enter: toggle span detail panel",
+      "F: focus the filter bar",
+      "E: toggle error-only filter",
+      "Home: jump to root span",
+      "End: jump to last span"
+    ],
+    "announcements": [
+      "Span: {service} {operation}, duration {duration}ms, {status}",
+      "Expanded {childCount} child spans under {operation}",
+      "Detail panel opened for {service} {operation}",
+      "Filter applied: showing {count} of {total} spans",
+      "Error span: {service} {operation} failed after {duration}ms"
+    ]
+  }
+}