@decantr/content 3.8.0

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@decantr/content",
+  "version": "3.8.0",
+  "description": "Official Decantr content corpus for AI frontend governance contracts, context, examples, and validation",
+  "keywords": [
+    "decantr",
+    "decantr-ai",
+    "ai-frontend-governance",
+    "content-corpus",
+    "design-contracts",
+    "ui-patterns",
+    "archetypes",
+    "blueprints",
+    "themes",
+    "content-health"
+  ],
+  "author": "Decantr AI",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/decantr-ai/decantr/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/decantr-ai/decantr.git",
+    "directory": "packages/content"
+  },
+  "homepage": "https://decantr.ai",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./schemas/*.json": "./schemas/*.json",
+    "./patterns/*.json": "./patterns/*.json",
+    "./themes/*.json": "./themes/*.json",
+    "./blueprints/*.json": "./blueprints/*.json",
+    "./archetypes/*.json": "./archetypes/*.json",
+    "./shells/*.json": "./shells/*.json"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "patterns",
+    "themes",
+    "blueprints",
+    "archetypes",
+    "shells",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "validate": "node validate.js",
+    "content:health": "node ../cli/dist/bin.js content-health --ci --fail-on error --markdown --output content-health-summary.md",
+    "content:health:json": "node ../cli/dist/bin.js content-health --json --output content-health-report.json",
+    "content:health:suppressions": "node scripts/audit-content-health-suppressions.js",
+    "content:intelligence": "node scripts/audit-content-intelligence.js --report-json=content-intelligence-report.json --summary-markdown=content-intelligence-summary.md",
+    "content:certify": "node scripts/certify-registry-v2.js --report-json=content-certification-report.json --summary-markdown=content-certification-summary.md",
+    "registry:v2-certify": "pnpm run content:certify"
+  }
+}

package/patterns/account-settings.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "id": "account-settings",
+  "version": "1.1.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Account Settings",
+  "description": "Account management workspace with responsive settings navigation, grouped forms, and stable save/action zones for profile, security, preferences, and danger-zone flows.",
+  "dependencies": {
+    "patterns": {
+      "session-manager": "^1.0.0",
+      "settings-nav": "^1.0.0"
+    },
+    "styles": {},
+    "requires_core": {
+      "components": [
+        "Button",
+        "Avatar",
+        "Badge",
+        "icon"
+      ],
+      "charts": []
+    }
+  },
+  "components": [
+    "Button",
+    "Avatar",
+    "Badge",
+    "icon"
+  ],
+  "default_preset": "profile",
+  "presets": {
+    "profile": {
+      "description": "Profile editing with settings navigation, avatar upload, name, email, bio, and a stable save zone.",
+      "components": [
+        "Button",
+        "Avatar",
+        "icon"
+      ],
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap8",
+        "slots": {
+          "nav": "Responsive settings navigation using vertical tabs on larger widths and horizontal tabs on small screens",
+          "avatar": "Avatar with upload/change button",
+          "form": "Name, email, bio inputs grouped in a content panel",
+          "save": "Save changes button in a stable action zone"
+        }
+      }
+    },
+    "security": {
+      "description": "Security settings with password change and MFA controls",
+      "components": [
+        "Button",
+        "Badge",
+        "icon"
+      ],
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap8",
+        "slots": {
+          "password": "Change password form",
+          "mfa": "MFA enable/disable toggle with status",
+          "sessions": "Session manager component"
+        }
+      }
+    },
+    "preferences": {
+      "description": "User preferences for theme, notifications, language",
+      "components": [
+        "Button",
+        "icon"
+      ],
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap8",
+        "slots": {
+          "theme": "Theme selector (light/dark/auto)",
+          "notifications": "Notification toggles",
+          "language": "Language/locale selector"
+        }
+      }
+    },
+    "danger-zone": {
+      "description": "Account deletion with typed confirmation",
+      "components": [
+        "Button",
+        "icon"
+      ],
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap6",
+        "slots": {
+          "warning": "Deletion warning message",
+          "confirm": "Typed confirmation input",
+          "delete": "Delete account button"
+        }
+      }
+    }
+  },
+  "layout_hints": {
+    "active_state": "Active nav/tab item should have a visible indicator: accent-colored left border (for vertical nav) or bottom border (for horizontal tabs), plus accent text color.",
+    "nav_position": "For settings pages, use a vertical tab nav on the left at larger widths. On small screens, switch to a horizontal scrollable tab strip or segmented control without changing the content spacing rhythm.",
+    "spacing": "Nav items have consistent padding. Active item stands out but doesn't shift layout. Content cards should share the same shell inset rhythm as the rest of the dashboard.",
+    "cta_treatment": "Primary save/update actions should sit in a stable action zone and feel distinct from secondary utility buttons such as avatar change, sign out, or cancel."
+  },
+  "visual_brief": "Settings page with vertical navigation tabs on the left (Profile, Security, Notifications, Danger Zone) and form content on the right. Active tab highlighted with an accent border. On small screens, the nav becomes a horizontal scrollable strip while the forms keep the same comfortable shell spacing. Each settings section is a d-surface card with grouped form fields, section heading, and a stable save action zone.",
+  "responsive": {
+    "mobile": "Collapse the workspace to a single column with a horizontal scrollable tab strip or segmented control above the active section. Keep the content max-width comfortable and place save or destructive actions close to the relevant field group.",
+    "tablet": "Allow either a narrow left settings rail or a horizontal tab strip depending on width. Preserve stable action zones and avoid overly wide form rows.",
+    "desktop": "Use a clear split between navigation and content with enough gap to keep settings work readable. Do not let profile or preferences forms stretch edge-to-edge."
+  },
+  "motion": {
+    "micro": "Active nav indicators, save confirmations, and destructive warning states may animate softly over 150-200ms.",
+    "transitions": "Switching between settings sections should cross-fade or slide minimally so the workspace still feels stable and operational.",
+    "ambient": "Avoid decorative ambient motion in settings surfaces. Keep movement functional and low-noise."
+  },
+  "interactions": [
+    "inline-edit",
+    "animate-on-mount",
+    "keyboard-navigation"
+  ],
+  "accessibility": {
+    "role": "region",
+    "aria-label": "Account settings workspace",
+    "keyboard": [
+      "Tab moves through settings navigation, fields, and actions in source order.",
+      "Arrow keys may move between tab-style navigation items when rendered as a tab list.",
+      "Enter or Space activates save, cancel, and destructive confirmation actions."
+    ],
+    "announcements": [
+      "Announce settings section changes such as 'Security settings selected'.",
+      "Announce save success, validation errors, and destructive confirmations clearly."
+    ],
+    "focus_management": "When changing settings sections, move focus to the section heading or first field. Keep destructive actions visually separated and reachable without trapping focus."
+  },
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_flex _col _gap8",
+    "slots": {
+      "form": "Settings form fields",
+      "save": "Save button"
+    }
+  },
+  "composition": {
+    "AccountSettings": "Container(d-section, split) > [SettingsNav + SettingsContent]",
+    "SettingsNav": "SettingsNavPattern(vertical-tabs, responsive)",
+    "SettingsContent": "Panel(d-surface, flex-col, gap-8) > [SectionHeading + AvatarUpload? + FormFields + ActionZone]"
+  }
+}

package/patterns/activity-feed.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "id": "activity-feed",
+  "version": "1.1.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Activity Feed",
+  "description": "Chronological list of activity events with avatars, timestamps, and action descriptions. The feed owns its rows and grouping, not the outer section spacing around it.",
+  "dependencies": {
+    "patterns": {},
+    "styles": {},
+    "requires_core": {
+      "components": [
+        "Avatar",
+        "Badge",
+        "Button",
+        "Separator",
+        "ScrollArea",
+        "icon"
+      ],
+      "charts": []
+    }
+  },
+  "components": [
+    "Avatar",
+    "Badge",
+    "Button"
+  ],
+  "default_preset": "standard",
+  "presets": {
+    "standard": {
+      "description": "Vertical timeline with avatar, user name, action text, timestamp. Grouped by date.",
+      "components": [
+        "Avatar",
+        "Badge",
+        "Button",
+        "Separator",
+        "icon"
+      ],
+      "layout": {
+        "layout": "column",
+        "atoms": "_flex _col _gap2 _w[100%]",
+        "slots": {
+          "date-header": "Date group separator with _textsm _fgmuted _fontmedium",
+          "feed-item": "Single activity row: _flex _row _gap3 _items[start]",
+          "avatar": "User Avatar with fallback initials",
+          "content": "Action text with user name (_fontmedium) and description",
+          "timestamp": "Relative time label with _textsm _fgmuted",
+          "load-more": "Button at bottom to load older activities"
+        }
+      }
+    },
+    "compact": {
+      "description": "Dense list without avatars, just icon + text + relative time",
+      "components": [
+        "Badge",
+        "Button",
+        "icon"
+      ],
+      "layout": {
+        "layout": "column",
+        "atoms": "_flex _col _gap1 _w[100%]",
+        "slots": {
+          "feed-item": "Compact row: _flex _row _gap2 _aic",
+          "icon": "Small type icon indicator",
+          "content": "Action text in single line, truncated",
+          "timestamp": "Relative time, right-aligned"
+        }
+      }
+    },
+    "detailed": {
+      "description": "Each activity is a mini-card with full context, attachments, and reply option",
+      "components": [
+        "Avatar",
+        "Badge",
+        "Button",
+        "icon"
+      ],
+      "layout": {
+        "layout": "column",
+        "atoms": "_flex _col _gap4 _w[100%]",
+        "slots": {
+          "feed-card": "Activity card: _flex _col _gap2 _p4 _r3 _border _border[var(--border)]",
+          "card-header": "Avatar + user + timestamp row",
+          "card-body": "Full action description and optional attachment preview",
+          "card-actions": "Reply, Like, Share action Buttons"
+        }
+      }
+    }
+  },
+  "visual_brief": "Vertical timeline of activity events grouped by date. Each date group starts with a muted, small-text date header. Individual feed items are horizontal rows: a circular avatar (with fallback initials) on the left, then a content block with the user name in medium-weight text followed by the action description in normal weight, and a relative timestamp (e.g. '2h ago') in small muted text right-aligned or below. Items are separated by subtle dividers or spacing. The compact preset drops avatars and uses small type-indicator icons instead. The detailed preset wraps each item in a bordered card with attachment previews and action buttons (reply, like).",
+  "responsive": {
+    "mobile": "Full-width feed. Avatar size reduces to 32px. Timestamp moves below the content text instead of right-aligned. Detailed preset card actions stack vertically. Load-more button goes full-width.",
+    "tablet": "Standard layout with avatars at 36px. Timestamp stays inline right-aligned. Comfortable spacing with gap3.",
+    "desktop": "Full layout with 40px avatars. Generous spacing. Detailed preset shows attachment previews inline. Actions row is fully horizontal."
+  },
+  "motion": {
+    "micro": "Feed item rows highlight on hover with subtle background transition over 150ms. Action buttons in detailed preset scale on hover.",
+    "transitions": "New activity items slide in from the top with 300ms ease-out translateY(-10px) to translateY(0) plus opacity 0 to 1. Staggered by 80ms per item when multiple arrive. Load-more items fade in from below."
+  },
+  "interactions": [
+    "animate-on-mount",
+    "stagger-children",
+    "real-time-updates",
+    "hover-reveal",
+    "scroll-reveal"
+  ],
+  "accessibility": {
+    "role": "feed",
+    "aria-label": "Activity feed",
+    "keyboard": [
+      "Tab moves through feed items and inline actions in chronological order.",
+      "Load-more controls remain reachable after the newest visible group."
+    ],
+    "announcements": [
+      "New activity items should be announced without rereading the full feed.",
+      "Date group headers should remain semantically distinct from entries."
+    ],
+    "focus_management": "Do not steal focus when new events arrive. Preserve the reader's current position unless they explicitly choose to jump to the latest item."
+  },
+  "default_layout": {
+    "layout": "column",
+    "atoms": "_flex _col _gap2 _w[100%]",
+    "slots": {
+      "date-header": "Date group separator with _textsm _fgmuted _fontmedium",
+      "feed-item": "Single activity row: _flex _row _gap3 _items[start]",
+      "avatar": "User Avatar with fallback initials",
+      "content": "Action text with user name and description",
+      "timestamp": "Relative time label",
+      "load-more": "Button at bottom to load older activities"
+    }
+  },
+  "io": {
+    "consumes": [
+      "search",
+      "view",
+      "filters"
+    ],
+    "produces": [],
+    "actions": [
+      "load-more",
+      "mark-read"
+    ]
+  },
+  "layout_hints": {
+    "event_treatment": "Each event row: small colored dot (8px, color by event type) + timestamp (mono-data, text-xs) + description. Hover: subtle bg highlight.",
+    "grouping": "Group events by date. Date header: d-label with accent left-border. Today/Yesterday labels, then ISO dates.",
+    "empty_state": "Encouraging: 'No activity yet. Publish your first item to see it here.'"
+  },
+  "composition": {
+    "ActivityFeed": "Container(d-data, flex-col, full-width) > [DateGroup[] + LoadMore?(d-interactive)]",
+    "DateGroup": "Group(d-data) > [DateHeader(d-annotation, text-muted) + FeedItem[]]",
+    "FeedItem": "Row(d-data-row, hoverable) > [Avatar(fallback-initials) + Content(flex-col) > [UserName(font-medium) + ActionText] + Timestamp(mono-data, text-xs, text-muted)]"
+  }
+}

package/patterns/adaptive-density-panel.json

@@ -0,0 +1,130 @@
+{
+  "id": "adaptive-density-panel",
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Adaptive Density Panel",
+  "description": "Self-adjusting container panel that smoothly transitions between information density levels — auto mode uses viewport width and user behavior to determine optimal density, with manual compact/comfortable/spacious overrides.",
+  "category": "ambient",
+  "tags": [
+    "2027",
+    "frontier",
+    "ambient",
+    "density",
+    "adaptive",
+    "responsive",
+    "AI",
+    "layout",
+    "accessibility"
+  ],
+  "components": [
+    "DensityPanel",
+    "DensityControl",
+    "ContentRegion",
+    "OverflowIndicator",
+    "FocusMask"
+  ],
+  "default_preset": "auto",
+  "presets": {
+    "auto": {
+      "description": "AI-determined density that adapts based on viewport width, scroll velocity, time-on-page, and content volume — narrows spacing when scanning, widens when reading deeply",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _flex-col _gap-auto _transition-all _duration-300"
+      }
+    },
+    "compact": {
+      "description": "Maximum information density with tight spacing, small text, and minimal padding — optimized for power users who need to see many items at once, data tables, and dashboard views",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _flex-col _gap-1 _text-xs _p-2"
+      }
+    },
+    "comfortable": {
+      "description": "Default balanced density with standard spacing, readable text size, and moderate padding — the general-purpose setting suitable for most content and users",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _flex-col _gap-3 _text-sm _p-4"
+      }
+    },
+    "spacious": {
+      "description": "Minimal information density with generous spacing, larger text, and ample padding — focus mode that reduces visual noise and highlights fewer items for deep reading or presentation",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _flex-col _gap-6 _text-base _p-6"
+      }
+    }
+  },
+  "visual_brief": "A container panel (d-section, rounded-xl, border, bg-surface) whose internal spacing, font sizes, and padding animate smoothly between density levels. The panel has a header bar and a content area. HEADER: a slim horizontal bar (flex, items-center, justify-between, px matching current density padding, py-2, border-b). On the left: an optional section title (font-semibold, size matching density). On the right: the DensityControl — a segmented control with 3 clickable segments representing density levels. Each segment shows a symbolic icon: compact = three tightly spaced horizontal lines (hamburger-like, 12px), comfortable = three moderately spaced lines (14px), spacious = two widely spaced lines (16px). The active segment has bg-accent/15% and text-accent. Inactive segments are text-muted. The control is 72px wide total, rounded-full, with a 1px border. In auto mode, a small 'A' badge overlays the control indicating automatic mode; clicking any segment overrides auto with the selected density. A long-press on the auto badge re-engages auto mode. CONTENT AREA: the ContentRegion fills the remaining panel space. Its CSS custom properties change per density level — COMPACT: --density-gap: 4px; --density-text: 0.75rem; --density-padding: 8px; --density-line-height: 1.3. COMFORTABLE: --density-gap: 12px; --density-text: 0.875rem; --density-padding: 16px; --density-line-height: 1.5. SPACIOUS: --density-gap: 24px; --density-text: 1rem; --density-padding: 24px; --density-line-height: 1.7. All properties transition simultaneously over 300ms ease-in-out, creating a smooth breathing effect as the panel expands or contracts. Children within the content region inherit these custom properties for their own gap, font-size, padding, and line-height. OVERFLOW: when density hides items (compact can show 20 items, comfortable 12, spacious 6 in the same viewport height), an OverflowIndicator appears at the bottom — a subtle bar (h-8, flex, items-center, justify-center, bg-gradient from transparent to surface, text-xs, text-muted) reading '+8 more items' or 'Scroll for more'. The count updates dynamically as density changes. FOCUS MASK: in spacious mode, an optional FocusMask can dim non-hovered items to 40% opacity, creating a spotlight effect where only the item under the cursor/focus is fully visible. Items transition opacity over 200ms on hover. The mask is disabled in compact and comfortable modes.",
+  "layout_hints": {
+    "container": "block section, fills available width",
+    "note": "The DensityPanel works best as a container wrapping list-like content (feed items, table rows, card grids). The density CSS custom properties should be inherited by child components for consistent density scaling.",
+    "auto_algorithm": "Auto density uses: (1) viewport width — under 640px defaults to compact, 640–1024px comfortable, over 1024px comfortable. (2) Scroll velocity — fast scrolling (>200px/s sustained for 2s) temporarily shifts to compact for scanning. (3) Idle time — if user stops scrolling for 10s, shift toward comfortable/spacious. (4) Content volume — if total items exceed 2x viewport capacity, prefer compact. These signals are weighted and blended, not hard thresholds.",
+    "transition_smoothness": "All density properties MUST transition together in a single 300ms animation. Do not stagger — simultaneous transition of gap, font-size, padding, and line-height creates a unified breathing effect. Use the CSS transition shorthand: transition: all 300ms ease-in-out.",
+    "content_awareness": "Child components should declare a data-density-aware attribute. The DensityPanel will set --density-level: compact|comfortable|spacious as a CSS custom property and data-density attribute on the root, allowing children to adapt beyond just spacing (e.g., hiding secondary text in compact, showing avatars only in comfortable+)."
+  },
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_flex _flex-col _rounded-xl _border _bg-surface _overflow-hidden _transition-all _duration-300",
+    "slots": {
+      "density-panel": "The root container element. A d-section with rounded-xl, border, bg-surface, overflow-hidden. Sets CSS custom properties based on current density: --density-gap, --density-text, --density-padding, --density-line-height, --density-level. These properties are set on the element's style attribute and transitioned. The panel also sets a data-density attribute ('compact', 'comfortable', 'spacious') on the root element for CSS selector-based child adaptation. In auto mode, the panel runs a lightweight observer: (1) ResizeObserver on the panel for viewport changes, (2) scroll event listener on ContentRegion for velocity tracking, (3) IntersectionObserver on child items for content volume assessment. Density changes are debounced by 500ms to prevent jitter.",
+      "density-control": "A segmented control in the panel header for manual density selection. Structure: a flex container (inline-flex, items-center, rounded-full, border, bg-muted/5%, h-7). Three segment buttons, each ~24px wide: COMPACT segment contains an SVG icon of 3 tightly stacked horizontal lines (each 10px wide, 1.5px tall, gap: 2px between lines). COMFORTABLE segment: 3 lines with gap: 3px. SPACIOUS segment: 2 lines with gap: 5px. Each segment has padding: 4px 6px, rounded-full (for the active indicator), cursor: pointer. The active segment has background: var(--d-accent) at 15% opacity, and the icon strokes use var(--d-accent). Inactive segments: icon strokes use var(--d-muted). Transition between active states: background-color 200ms ease-out. When auto mode is active, a small circular badge (12px, bg-accent, text-accent-foreground, text-[8px], font-bold, absolute top: -4px, right: -4px) shows 'A'. Clicking a segment disables auto and locks to that density. Re-enabling auto: long-press (800ms) on any segment, or a small 'Auto' text button adjacent to the control.",
+      "content-region": "The main content area below the header. Uses flex-col layout with gap: var(--density-gap). Padding: var(--density-padding). Font-size: var(--density-text). Line-height: var(--density-line-height). The content region holds child items (passed via slot/children). All spacing and text sizing is driven by the CSS custom properties, so any content placed inside automatically respects the current density. The region has overflow-y: auto for scrolling when content exceeds the panel height. Scroll events on this region feed into the auto-density algorithm (velocity tracking). The region also tracks which children are visible via IntersectionObserver to power the OverflowIndicator count.",
+      "overflow-indicator": "A fixed-bottom bar within the content region that appears when content overflows the visible area. Structure: a div (sticky, bottom: 0, h-8, flex, items-center, justify-center, pointer-events-none except for the text link). Background: a gradient from transparent (top) to var(--d-surface) (bottom) over 32px, creating a smooth fade-out of content. Centered text: '{N} more items' or 'Scroll for more' in text-xs, text-muted. The count N is computed as total children minus visible children (determined by IntersectionObserver). When all items are visible, the indicator is hidden (display: none). The indicator animates in/out with opacity 0→1 over 200ms when visibility changes. Optionally, the text is a clickable link that scrolls to reveal the next set of items.",
+      "focus-mask": "An optional overlay effect activated in spacious density mode. When enabled, all content items within the ContentRegion that are NOT currently hovered or focused receive opacity: 0.4 and a slight blur (filter: blur(0.5px)). The hovered/focused item remains at opacity: 1, no blur, and may receive a subtle scale(1.01) lift. This creates a spotlight/focus effect ideal for presentations or deep reading. Transitions: opacity 200ms ease-out, filter 200ms ease-out, transform 200ms ease-out. The mask is controlled by a parent-level CSS rule: [data-density='spacious'] .content-item:not(:hover):not(:focus-within) { opacity: 0.4; filter: blur(0.5px); }. Disabled in compact and comfortable modes — all items remain at full opacity."
+    }
+  },
+  "accessibility": {
+    "role": "region",
+    "aria-label": "Adaptive density content panel",
+    "announcements": [
+      "Density changed to {level}",
+      "Auto density mode {enabled|disabled}",
+      "Showing {visible} of {total} items",
+      "{N} more items available — scroll to view",
+      "Focus mode {enabled|disabled}"
+    ],
+    "keyboard": [
+      "Ctrl+Shift+1: set compact density",
+      "Ctrl+Shift+2: set comfortable density",
+      "Ctrl+Shift+3: set spacious density",
+      "Ctrl+Shift+0: toggle auto density",
+      "Tab: cycle through density control segments, then into content items",
+      "Arrow Up/Down: scroll content region",
+      "F: toggle focus mask in spacious mode"
+    ]
+  },
+  "responsive": {
+    "mobile": "DensityControl moves from the header to a floating action button (40px circle, bottom-right of panel, shadow-lg). Tapping cycles through density levels. Auto mode defaults to compact on viewport < 375px. OverflowIndicator always visible if content overflows. FocusMask disabled on touch devices (no hover).",
+    "tablet": "DensityControl in header as standard. Auto mode responsive to both viewport width and orientation changes. FocusMask available on devices with fine pointer (stylus)."
+  },
+  "motion": {
+    "micro": {
+      "density-control-hover": "segment bg-accent/10% 150ms ease-out",
+      "density-control-active": "segment scale(0.95) 100ms",
+      "overflow-text-hover": "text color muted→accent 150ms"
+    },
+    "transitions": {
+      "density-change": "all CSS custom properties (gap, font-size, padding, line-height) transition simultaneously over 300ms ease-in-out — unified breathing effect",
+      "overflow-show": "opacity 0→1 200ms ease-out",
+      "overflow-hide": "opacity 1→0 200ms ease-in",
+      "focus-mask-engage": "non-hovered items opacity 1→0.4 + blur 0→0.5px 200ms ease-out",
+      "focus-mask-disengage": "all items opacity→1 + blur→0 200ms ease-out"
+    },
+    "ambient": {
+      "auto-density-shift": "density transitions triggered by user behavior are slightly slower (500ms) than manual switches (300ms) to feel organic rather than jarring",
+      "auto-badge-pulse": "the 'A' badge on density control has a subtle opacity oscillation (0.7→1→0.7) over 3s ease-in-out infinite to indicate auto mode is actively monitoring"
+    }
+  },
+  "interactions": [
+    "click-select",
+    "animate-on-mount"
+  ],
+  "composition": {
+    "AdaptiveDensityPanel": "Section(d-section, rounded-xl, border, bg-surface) > [Header(flex, border-b) > [Title? + DensityControl] + ContentRegion(flex-col, density-responsive) > [Content* + OverflowIndicator?] + FocusMask?]",
+    "DensityControl": "SegmentedControl(inline-flex, rounded-full, border) > [CompactSegment + ComfortableSegment + SpaciousSegment] + AutoBadge?(12px, circle, accent)",
+    "ContentRegion": "Div(flex-col, gap: var(--density-gap), p: var(--density-padding), overflow-y-auto) > [ChildItems*(density-aware)]",
+    "OverflowIndicator": "Div(sticky, bottom-0, h-8, gradient-fade, text-center) > CountText(text-xs, text-muted)",
+    "FocusMask": "CSS-rule(applied-via-data-density='spacious', dims non-hovered items to 40% opacity + subtle blur)"
+  }
+}

package/patterns/agent-handoff-zone.json

@@ -0,0 +1,97 @@
+{
+  "id": "agent-handoff-zone",
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=2.0.0",
+  "name": "Agent Handoff Zone",
+  "description": "A transition portal for agent-to-agent context transfer that visualizes the source agent, target agent, transferred context summary, animated handoff progress, and an approval workflow for human-in-the-loop oversight.",
+  "category": "agentic",
+  "tags": [
+    "2026",
+    "agentic",
+    "handoff",
+    "context-transfer",
+    "approval",
+    "orchestration"
+  ],
+  "components": [
+    "AgentCard",
+    "ContextSummary",
+    "HandoffProgress",
+    "Timeline",
+    "ApproveButton",
+    "RejectButton"
+  ],
+  "default_preset": "standard",
+  "presets": {
+    "standard": {
+      "description": "Full handoff view with source and target agent cards flanking a central transfer visualization, context preview below, and approval actions at the bottom — intended as a focused modal or dedicated page section",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap6 _p6 _rounded-lg _border _bg-surface"
+      }
+    },
+    "compact": {
+      "description": "Single-row summary for notification bars or feed items — shows agent avatars with an arrow between them, one-line context summary, and inline approve/reject icon buttons",
+      "layout": {
+        "layout": "row",
+        "atoms": "_flex _aic _gap4 _px4 _py3 _rounded _border _bg-surface"
+      }
+    },
+    "inline-chat": {
+      "description": "Embedded within a chat message stream — styled as a special system message card showing the handoff with minimal chrome, context as a collapsible section, and small action buttons",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap3 _p4 _rounded _border-dashed _bg-surface-subtle"
+      }
+    }
+  },
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_flex _col _gap6 _p6 _rounded-lg _border _bg-surface",
+    "slots": {
+      "source-agent": "Left-positioned agent card showing the handing-off agent. Displays agent name, role/type label (e.g., 'Research Agent'), avatar or icon, and current status badge (completing/handing-off). Card has a subtle left-border accent in the agent's assigned color. Shows a brief summary of what this agent accomplished before initiating the handoff (e.g., '3 sources analyzed, 2 key findings'). Card dims slightly with reduced opacity once the handoff completes to visually signal it is no longer active.",
+      "target-agent": "Right-positioned agent card showing the receiving agent. Same structure as source-agent but with a right-border accent. Status badge shows 'receiving' during transfer, then 'active' once handoff completes. If the target agent hasn't started yet, card renders in a waiting/skeleton state with a subtle pulse animation. Agent capabilities are listed as small tags below the name (e.g., 'code-gen', 'testing').",
+      "context-preview": "A collapsible panel between/below the agent cards showing the exact context being transferred. Renders as a structured summary with sections: 'Conversation History' (message count + token estimate), 'Key Decisions' (bulleted list of decisions made by source agent), 'Active Constraints' (tags for any rules or guardrails being passed), and 'Artifacts' (list of files, code snippets, or data objects being transferred with size indicators). Each section is independently collapsible. A small 'View Raw' toggle shows the full serialized context JSON in a scrollable code block. Total transfer size is displayed as a badge (e.g., '12.4 KB context').",
+      "handoff-animation": "A visual connector between the source-agent and target-agent cards. In the standard layout, renders as a horizontal animated beam or particle stream flowing left-to-right. Uses a three-phase animation: (1) 'packaging' — dots gather at the source card edge, (2) 'transferring' — dots stream across to target in a flowing arc, (3) 'received' — dots absorb into the target card with a brief glow. During the approval-pending state, the animation pauses mid-stream with a pulsing hold indicator. Color follows the theme's primary/accent. The animation area also displays a percentage progress indicator and estimated time remaining.",
+      "status-timeline": "A horizontal timeline strip below the main handoff visualization showing key events in chronological order: 'Handoff initiated', 'Context packaged', 'Awaiting approval' (if approval required), 'Transfer in progress', 'Handoff complete'. Each event is a small dot connected by a line, with the current step highlighted and future steps dimmed. Timestamps appear on hover. If the handoff fails or is rejected, the timeline shows the failure point with an error color and a brief reason.",
+      "approval-actions": "A row of action buttons that appears when the handoff requires human-in-the-loop approval. Contains: ApproveButton (primary, shows 'Approve Handoff' with a checkmark icon), RejectButton (destructive/outline, shows 'Reject' with an X icon), and an optional 'Modify Context' text button that opens the context-preview in edit mode for humans to redact or add context before approving. When no approval is needed (auto-handoff), this slot renders a subtle 'Auto-approved' label with a timestamp. After action is taken, buttons are replaced with a status label showing the decision and who made it."
+    }
+  },
+  "accessibility": {
+    "role": "region",
+    "aria-label": "Agent handoff from {source} to {target}",
+    "announcements": [
+      "Handoff initiated from {source} agent to {target} agent",
+      "Awaiting your approval to transfer context",
+      "Handoff approved, transfer in progress",
+      "Handoff complete, {target} agent is now active",
+      "Handoff rejected by {user}"
+    ],
+    "keyboard": [
+      "Tab: navigate between source card, context preview, target card, and action buttons",
+      "Enter: expand/collapse context preview sections",
+      "A: approve handoff (when approval actions are focused)",
+      "R: reject handoff (when approval actions are focused)",
+      "Escape: close handoff detail view"
+    ]
+  },
+  "responsive": {
+    "mobile": "Agent cards stack vertically (source on top, target below) with the handoff animation rendered as a vertical downward flow between them. Context preview defaults to collapsed. Approval buttons render full-width stacked. Timeline becomes a vertical strip on the left edge.",
+    "tablet": "Standard horizontal layout maintained. Context preview starts collapsed to save space. Approval buttons remain inline. Touch targets for approve/reject increased to 48px minimum height."
+  },
+  "visual_brief": "Horizontal two-card layout with source agent on the left and target agent on the right, connected by an animated transfer beam. Each agent card shows avatar, name, role label, and status badge with a colored left/right border accent. A collapsible context-preview panel sits below the cards displaying transferred data sections. A horizontal status timeline runs underneath with dot-connected steps. Approval action buttons (Approve, Reject) anchor at the bottom. Compact preset collapses to a single row with inline avatars and an arrow between them.",
+  "interactions": [
+    "drag-nodes",
+    "animate-on-mount",
+    "status-pulse"
+  ],
+  "composition": {
+    "AgentHandoffZone": "Container(d-section, flex-col, gap-6) > [AgentRow + ContextPreview + StatusTimeline + ApprovalActions?]",
+    "AgentRow": "Row(d-surface, gap-6) > [AgentCard(source, accent-left) + HandoffAnimation(animated) + AgentCard(target, accent-right)]",
+    "AgentCard": "Card(d-surface) > [Avatar + Name(heading4) + RoleLabel(d-annotation) + StatusBadge(d-annotation, data-status)]",
+    "ContextPreview": "Panel(d-surface, collapsible) > [Section(collapsible)[] + ViewRawToggle?(d-interactive)]",
+    "StatusTimeline": "Track(d-data) > TimelineStep(dot-connected)[]",
+    "ApprovalActions": "Row(d-interactive) > [ApproveButton(variant: primary) + RejectButton(variant: destructive) + ModifyButton?(variant: ghost)]"
+  }
+}