@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/applying-slds/metadata/blueprints/components/docked-form-footer.yaml

@@ -0,0 +1,161 @@
+name: "Docked Form Footer"
+
+description: "A fixed footer component that docks to the bottom of the viewport, typically containing form action buttons like Save and Cancel. It remains visible as the user scrolls through long forms."
+
+category: "Layout"
+
+slds_classes:
+  root: "slds-docked-form-footer"
+  elements: []
+  modifiers: []
+  states: []
+
+variants:
+  - name: "Base"
+    description: "Standard docked footer with centered content"
+    classes: ["slds-docked-form-footer"]
+    usage_context: "Default footer for long forms that need persistent action buttons"
+    differences: "Fixed to bottom of viewport with shadow elevation"
+
+lightning_component:
+  name: ""
+  url: "https://developer.salesforce.com/docs/component-library/overview/components"
+  mapping_notes: "No direct Lightning Base Component - implement with custom footer and CSS positioning"
+
+accessibility:
+  keyboard_support:
+    - "Tab to navigate to footer buttons"
+    - "Enter or Space to activate buttons"
+  screen_reader:
+    - "Footer landmark announced if using footer element"
+    - "Button labels announced clearly"
+    - "Action sequence communicated"
+  aria_attributes:
+    - "role='contentinfo' if using div instead of footer"
+    - "Buttons should have clear aria-label if needed"
+
+usage_guidelines:
+  when_to_use:
+    - "For long forms that extend beyond viewport height"
+    - "When form actions need to remain always visible"
+    - "For edit or create flows with Save/Cancel actions"
+    - "In modal or page contexts with critical actions"
+  when_not_to_use:
+    - "For short forms that fit in viewport"
+    - "When inline form actions are sufficient"
+    - "In contexts where fixed positioning causes issues"
+    - "On small screens where footer takes too much space"
+  best_practices:
+    - "Keep action buttons clearly labeled and visible"
+    - "Place primary action on the right (e.g., Save)"
+    - "Include Cancel or secondary action on the left"
+    - "Ensure footer doesn't obscure important content"
+    - "Consider mobile viewport height limitations"
+    - "Provide adequate padding around buttons"
+  common_mistakes:
+    - "Overcrowding footer with too many actions"
+    - "Poor color contrast on footer background"
+    - "Forgetting to account for footer height in page layout"
+    - "Not handling mobile viewport properly"
+    - "Missing keyboard navigation support"
+
+code_examples:
+  - title: "Basic Docked Form Footer"
+    code: |
+      <div class="slds-docked-form-footer">
+        <button class="slds-button slds-button_neutral">Cancel</button>
+        <button class="slds-button slds-button_brand">Save</button>
+      </div>
+    description: "Simple docked footer with Save and Cancel buttons"
+  - title: "Docked Footer with Multiple Actions"
+    code: |
+      <div class="slds-docked-form-footer">
+        <div class="slds-grid slds-grid_align-spread slds-wrap">
+          <div class="slds-col slds-no-flex">
+            <button class="slds-button slds-button_neutral">Cancel</button>
+          </div>
+          <div class="slds-col slds-no-flex">
+            <div class="slds-button-group" role="group">
+              <button class="slds-button slds-button_neutral">Save Draft</button>
+              <button class="slds-button slds-button_brand">Save &amp; Submit</button>
+            </div>
+          </div>
+        </div>
+      </div>
+    description: "Docked footer with multiple action options"
+  - title: "Docked Footer in Form Context"
+    code: |
+      <div class="slds-card">
+        <div class="slds-card__header slds-grid">
+          <header class="slds-media slds-media_center slds-has-flexi-truncate">
+            <div class="slds-media__body">
+              <h2 class="slds-card__header-title">
+                <span>Edit Contact</span>
+              </h2>
+            </div>
+          </header>
+        </div>
+        <div class="slds-card__body slds-card__body_inner" style="padding-bottom: 5rem;">
+          <form>
+            <div class="slds-form-element">
+              <label class="slds-form-element__label" for="input-01">
+                <abbr class="slds-required" title="required">* </abbr>First Name
+              </label>
+              <div class="slds-form-element__control">
+                <input type="text" id="input-01" class="slds-input" required />
+              </div>
+            </div>
+            <div class="slds-form-element">
+              <label class="slds-form-element__label" for="input-02">
+                <abbr class="slds-required" title="required">* </abbr>Last Name
+              </label>
+              <div class="slds-form-element__control">
+                <input type="text" id="input-02" class="slds-input" required />
+              </div>
+            </div>
+            <!-- More form fields... -->
+          </form>
+        </div>
+      </div>
+      <div class="slds-docked-form-footer">
+        <button class="slds-button slds-button_neutral" type="button">Cancel</button>
+        <button class="slds-button slds-button_brand" type="submit">Save</button>
+      </div>
+    description: "Docked footer used with a form in a card, note padding-bottom on card body to prevent content overlap"
+
+styling_hooks:
+  - name: "--slds-g-color-neutral-base-95"
+    description: "Background color of the docked footer"
+    css_property: "background"
+
+dependencies:
+  css_files: ["docked-form-footer.css", "button.css"]
+  javascript:
+    - "Form submission handling"
+    - "Scroll position management"
+  icons: []
+  other_components: ["button", "button-group"]
+
+related_components:
+  - name: "Modal"
+    relationship: "alternative"
+    description: "Alternative pattern for forms in overlay context"
+  - name: "Page Header"
+    relationship: "complementary"
+    description: "Header component that pairs with form content"
+  - name: "Button"
+    relationship: "contains"
+    description: "Action buttons within the footer"
+
+references:
+  official_docs: "https://v1.lightningdesignsystem.com/components/docked-form-footer/"
+
+metadata:
+  version: "1.0.0"
+  last_updated: "2025-11-11"
+  author: "SLDS Documentation Team"
+  slds_version: "2.27.2"
+  review_status: "complete"
+  source: "official-slds"
+  notes: "Created from official SLDS documentation and design-system-internal source code"
+

package/skills/applying-slds/metadata/blueprints/components/docked-utility-bar.yaml

@@ -0,0 +1,175 @@
+name: Docked Utility Bar
+description: A persistent utility panel that remains docked at the bottom or side of the screen, providing quick access to
+  frequently used tools, actions, and information without interrupting the primary workflow.
+category: Actions
+slds_classes:
+  root: slds-utility-bar_container
+  elements:
+  - class: slds-utility-bar
+    description: Fixed bar at the bottom of viewport that contains items
+    purpose: Main utility bar element with fixed positioning and background
+  - class: slds-utility-bar__item
+    description: Individual utility item that invokes specific utility bar panel
+    purpose: Represents a single utility tool or action
+  - class: slds-utility-bar__action
+    description: Action button within utility bar
+    purpose: Interactive element for utility functions
+  - class: slds-utility-bar__text
+    description: Text content within utility bar actions
+    purpose: Contains label text for utility actions
+  modifiers:
+  - class: slds-utility-bar__item_pop-out
+    description: Modifier for utility item with panel popped out in new window
+    usage: When utility panel is opened in a separate window
+  states:
+  - class: slds-is-active
+    description: Active utility action state
+    trigger: Applied to currently active utility action
+  - class: slds-indicator_unread
+    description: Unread notification indicator
+    trigger: Applied when utility has unread notifications
+variants:
+- name: Base
+  description: Standard docked utility bar fixed at bottom of viewport
+  classes:
+  - slds-utility-bar_container
+  - slds-utility-bar
+  usage_context: Default implementation for utility access
+  differences: Fixed horizontal utility bar at bottom of screen
+- name: With Pop-out
+  description: Utility bar item with panel popped out in new window
+  classes:
+  - slds-utility-bar__item
+  - slds-utility-bar__item_pop-out
+  usage_context: When utility panel is opened in a separate window
+  differences: Visual indicator showing panel is popped out
+lightning_component:
+  name: No direct component
+  url: https://developer.salesforce.com/docs/component-library/overview/components
+  mapping_notes: No direct Lightning Base Component equivalent - typically implemented using custom components with lightning-button-group
+    patterns
+accessibility:
+  keyboard_support:
+  - Tab navigation through utility items
+  - Enter/Space to activate utility actions
+  - Arrow keys for utility bar navigation
+  - Escape to close expanded panels
+  screen_reader:
+  - Utility bar purpose and items announced
+  - Panel expansion state communicated
+  - Utility actions clearly described
+  aria_attributes:
+  - role='toolbar' for utility bar container
+  - role='button' for utility actions
+  - aria-expanded for expandable utilities
+  - aria-label for utility descriptions
+  - aria-controls for panel relationships
+usage_guidelines:
+  when_to_use:
+  - For frequently accessed tools and utilities
+  - When users need persistent access to functions
+  - For secondary tools that support primary workflows
+  - To provide quick actions without navigation
+  when_not_to_use:
+  - For primary navigation (use main navigation)
+  - For infrequently used features
+  - When screen space is severely limited
+  best_practices:
+  - Include only essential utilities
+  - Provide clear icons and labels
+  - Allow customization of utility order
+  - Handle responsive behavior gracefully
+  - Maintain consistent interaction patterns
+  common_mistakes:
+  - Overcrowding with too many utilities
+  - Unclear or ambiguous utility icons
+  - Poor responsive behavior on small screens
+  - Inconsistent interaction patterns
+code_examples:
+- title: Basic Docked Utility Bar
+  description: Standard utility bar with common tools and actions
+  code: "<div class=\"\" role=\"toolbar\" aria-label=\"Utility tools\">\n      <div class=\"\">\n        <div class=\"\">\n\
+    \          <button class=\"slds-button slds-button_icon\" aria-expanded=\"false\" aria-controls=\"utility-panel-1\" title=\"\
+    Notes\">\n            <svg class=\"slds-button__icon\" aria-hidden=\"true\">\n              <use xlink:href=\"/assets/icons/utility-sprite/svg/symbols.svg#note\"\
+    ></use>\n            </svg>\n            <span class=\"slds-assistive-text\">Open notes utility</span>\n          </button>\n\
+    \        </div>\n        <div class=\"\">\n          <button class=\"slds-button slds-button_icon slds-is-active\" aria-expanded=\"\
+    true\" aria-controls=\"utility-panel-2\" title=\"Calculator\">\n            <svg class=\"slds-button__icon\" aria-hidden=\"\
+    true\">\n              <use xlink:href=\"/assets/icons/utility-sprite/svg/symbols.svg#calculator\"></use>\n          \
+    \  </svg>\n            <span class=\"slds-assistive-text\">Open calculator utility</span>\n          </button>\n     \
+    \   </div>\n        <div class=\"\">\n          <button class=\"slds-button slds-button_icon\" aria-expanded=\"false\"\
+    \ aria-controls=\"utility-panel-3\" title=\"Timer\">\n            <svg class=\"slds-button__icon\" aria-hidden=\"true\"\
+    >\n              <use xlink:href=\"/assets/icons/utility-sprite/svg/symbols.svg#clock\"></use>\n            </svg>\n \
+    \           <span class=\"slds-assistive-text\">Open timer utility</span>\n          </button>\n        </div>\n     \
+    \   <div class=\"\">\n          <button class=\"slds-button slds-button_icon\" title=\"Help\">\n            <svg class=\"\
+    slds-button__icon\" aria-hidden=\"true\">\n              <use xlink:href=\"/assets/icons/utility-sprite/svg/symbols.svg#help\"\
+    ></use>\n            </svg>\n            <span class=\"slds-assistive-text\">Open help</span>\n          </button>\n \
+    \       </div>\n      </div>\n      </div>\n"
+- title: Utility Bar with Expanded Panel
+  description: Utility bar with an expanded utility panel showing detailed content
+  code: "<div class=\"slds-is-open\" role=\"toolbar\" aria-label=\"Utility tools\">\n      <div class=\"\" id=\"utility-panel-calculator\"\
+    \ role=\"dialog\" aria-labelledby=\"panel-title\">\n        <header class=\"\">\n          <h2 id=\"panel-title\" class=\"\
+    slds-text-heading_small\">Calculator</h2>\n          <button class=\"slds-button slds-button_icon slds-button_icon-border\"\
+    \ title=\"Close\">\n            <svg class=\"slds-button__icon\" aria-hidden=\"true\">\n              <use xlink:href=\"\
+    /assets/icons/utility-sprite/svg/symbols.svg#close\"></use>\n            </svg>\n            <span class=\"slds-assistive-text\"\
+    >Close calculator</span>\n          </button>\n        </header>\n        <div class=\"\">\n          <div class=\"slds-grid\
+    \ slds-grid_vertical\">\n            <div class=\"slds-col\">\n              <input type=\"text\" class=\"slds-input slds-text-align_right\"\
+    \ value=\"0\" readonly aria-label=\"Calculator display\">\n            </div>\n            <div class=\"slds-col slds-m-top_small\"\
+    >\n              <div class=\"slds-grid slds-wrap\">\n                <div class=\"slds-col slds-size_1-of-4 slds-p-around_xx-small\"\
+    >\n                  <button class=\"slds-button slds-button_neutral slds-size_1-of-1\">7</button>\n                </div>\n\
+    \                <div class=\"slds-col slds-size_1-of-4 slds-p-around_xx-small\">\n                  <button class=\"\
+    slds-button slds-button_neutral slds-size_1-of-1\">8</button>\n                </div>\n                <div class=\"slds-col\
+    \ slds-size_1-of-4 slds-p-around_xx-small\">\n                  <button class=\"slds-button slds-button_neutral slds-size_1-of-1\"\
+    >9</button>\n                </div>\n                <div class=\"slds-col slds-size_1-of-4 slds-p-around_xx-small\">\n\
+    \                  <button class=\"slds-button slds-button_brand slds-size_1-of-1\">÷</button>\n                </div>\n\
+    \              </div>\n            </div>\n          </div>\n        </div>\n      </div>\n      <div class=\"\">\n  \
+    \      <div class=\"\">\n          <button class=\"slds-button slds-button_icon\" title=\"Notes\">\n            <svg class=\"\
+    slds-button__icon\" aria-hidden=\"true\">\n              <use xlink:href=\"/assets/icons/utility-sprite/svg/symbols.svg#note\"\
+    ></use>\n            </svg>\n            <span class=\"slds-assistive-text\">Notes</span>\n          </button>\n     \
+    \   </div>\n        <div class=\"\">\n          <button class=\"slds-button slds-button_icon slds-is-active\" aria-expanded=\"\
+    true\" title=\"Calculator\">\n            <svg class=\"slds-button__icon\" aria-hidden=\"true\">\n              <use xlink:href=\"\
+    /assets/icons/utility-sprite/svg/symbols.svg#calculator\"></use>\n            </svg>\n            <span class=\"slds-assistive-text\"\
+    >Calculator (Active)</span>\n          </button>\n        </div>\n      </div>\n      </div>\n"
+- title: Vertical Utility Bar
+  description: Vertically oriented utility bar for side placement
+  code: "<div class=\"\" role=\"toolbar\" aria-label=\"Utility tools\">\n      <div class=\"\">\n        <div class=\"\">\n\
+    \          <button class=\"slds-button slds-button_icon\" title=\"Bookmarks\">\n            <svg class=\"slds-button__icon\"\
+    \ aria-hidden=\"true\">\n              <use xlink:href=\"/assets/icons/utility-sprite/svg/symbols.svg#bookmark\"></use>\n\
+    \            </svg>\n            <span class=\"slds-assistive-text\">Bookmarks</span>\n          </button>\n        </div>\n\
+    \        <div class=\"\">\n          <button class=\"slds-button slds-button_icon\" title=\"Recent Items\">\n        \
+    \    <svg class=\"slds-button__icon\" aria-hidden=\"true\">\n              <use xlink:href=\"/assets/icons/utility-sprite/svg/symbols.svg#recent\"\
+    ></use>\n            </svg>\n            <span class=\"slds-assistive-text\">Recent Items</span>\n          </button>\n\
+    \        </div>\n        <div class=\"\">\n          <button class=\"slds-button slds-button_icon\" title=\"Search\">\n\
+    \            <svg class=\"slds-button__icon\" aria-hidden=\"true\">\n              <use xlink:href=\"/assets/icons/utility-sprite/svg/symbols.svg#search\"\
+    ></use>\n            </svg>\n            <span class=\"slds-assistive-text\">Search</span>\n          </button>\n    \
+    \    </div>\n      </div>\n      </div>\n"
+dependencies:
+  css_files:
+  - docked-utility-bar.css
+  - button.css
+  - grid.css
+  - panel.css
+  javascript:
+  - docked-utility-bar.js
+  icons:
+  - utility-sprite.svg
+  other_components:
+  - button
+  - grid
+  - panel
+related_components:
+- name: Docked Composer
+  relationship: similar
+  description: Similar docked interface concept
+- name: Global Header
+  relationship: alternative
+  description: Alternative location for utility access
+- name: Button Group
+  relationship: depends-on
+  description: Uses button group patterns for utility items
+references:
+  official_docs: https://v1.lightningdesignsystem.com/components/docked-utility-bar/
+metadata:
+  version: 1.0.0
+  last_updated: '2025-11-12'
+  review_status: complete
+  notes: ' Cleaned invalid classes and CSS variables on 2025-11-12 using slds-plus.css as source of truth.'

package/skills/applying-slds/metadata/blueprints/components/drop-zone.yaml

@@ -0,0 +1,115 @@
+name: Drop Zone
+description: A component for screen building that provides a draggable drop target area where users can drop components or
+  elements. Indicates drop availability and provides visual feedback during drag operations.
+category: Complex Components
+slds_classes:
+  root: slds-drop-zone
+  elements:
+  - class: slds-drop-zone__label
+    description: Top label of the drop zone
+    purpose: Displays instructional text or title
+  - class: slds-drop-zone__label_container
+    description: Container for populated drop zone label
+    purpose: Wraps label content when zone contains items
+  - class: slds-drop-zone__label_button
+    description: Button within drop zone label
+    purpose: Interactive element in label area
+  - class: slds-drop-zone_drag__slot
+    description: Insertion point of drop zone
+    purpose: Target area where items are dropped
+  modifiers:
+  - class: slds-drop-zone_drag
+    description: Modifier indicating drop availability
+    purpose: Applied when component may be dropped in container
+  states: []
+variants:
+- name: Base
+  description: Standard drop zone for component placement
+  classes:
+  - slds-drop-zone
+  usage_context: Default drop zone for drag-and-drop interfaces
+  differences: Empty drop target ready to receive dragged items
+lightning_component:
+  name: ''
+  url: https://developer.salesforce.com/docs/component-library/overview/components
+  mapping_notes: No direct Lightning Base Component - implement with custom drag-and-drop JavaScript
+accessibility:
+  keyboard_support:
+  - Tab to focus on drop zone
+  - Enter or Space to activate alternative placement
+  - Arrow keys for keyboard-based positioning
+  screen_reader:
+  - Drop zone role and purpose announced
+  - Drag state changes announced
+  - Successful drop confirmed
+  aria_attributes:
+  - aria-label describing drop zone purpose
+  - aria-dropeffect indicating allowed operations
+  - aria-grabbed on draggable items
+  - role='region' or custom role for drop area
+usage_guidelines:
+  when_to_use:
+  - For screen or page builders
+  - When users need to arrange components visually
+  - For customizable dashboards or layouts
+  - In drag-and-drop interfaces
+  when_not_to_use:
+  - For simple file uploads (use file selector)
+  - When drag-and-drop adds unnecessary complexity
+  - For mobile-only experiences (touch drag can be difficult)
+  - When list reordering is sufficient
+  best_practices:
+  - Provide clear visual feedback during drag
+  - Show valid drop targets clearly
+  - Indicate when zone is ready to receive drops
+  - Provide alternative non-drag methods
+  - Handle touch interactions for mobile
+  - Show drop zone boundaries clearly
+  common_mistakes:
+  - Unclear drop target boundaries
+  - No visual feedback during drag
+  - Missing keyboard alternatives
+  - Poor mobile/touch support
+  - Not indicating valid vs invalid drops
+code_examples:
+- title: Basic Drop Zone
+  code: "<div class=\"slds-drop-zone\">\n  <span class=\"slds-drop-zone__label\">\n    Drop components here\n  </span>\n</div>\n"
+  description: Empty drop zone ready to receive components
+- title: Drop Zone in Drag State
+  code: "<div class=\"slds-drop-zone slds-drop-zone_drag\">\n  <span class=\"slds-drop-zone__label\">\n    Release to place\
+    \ component\n  </span>\n  <div class=\"slds-drop-zone_drag__slot\"></div>\n</div>\n"
+  description: Drop zone during active drag operation
+- title: Drop Zone with Content
+  code: "<div class=\"slds-drop-zone\">\n  <div class=\"slds-drop-zone__label_container\">\n    <button class=\"slds-button\
+    \ slds-drop-zone__label_button\">\n      Add Component\n    </button>\n  </div>\n  <div class=\"\">\n    <!-- Placed components\
+    \ appear here -->\n  </div>\n</div>\n"
+  description: Drop zone with placed content and add button
+styling_hooks: []
+dependencies:
+  css_files:
+  - drop-zone.css
+  javascript:
+  - Drag and drop event handlers
+  - Drop validation logic
+  - Visual feedback during drag
+  - Component placement logic
+  icons: []
+  other_components:
+  - button
+related_components:
+- name: File Selector
+  relationship: alternative
+  description: Alternative for file uploads
+- name: Builder Header
+  relationship: complementary
+  description: Often used together in builder interfaces
+references:
+  official_docs: https://v1.lightningdesignsystem.com/components/drop-zone/
+metadata:
+  version: 1.0.0
+  last_updated: '2025-11-11'
+  author: SLDS Documentation Team
+  slds_version: 2.27.2
+  review_status: complete
+  source: official-slds
+  notes: Created from official SLDS documentation and design-system-internal source code

package/skills/applying-slds/metadata/blueprints/components/dueling-picklist.yaml

@@ -0,0 +1,196 @@
+name: "Dueling Picklist"
+
+description: "A dueling-picklist is used to move options between two lists and is often referred to as a multi-select. Sometimes, the list options can then be re-ordered, depending on the use case."
+
+category: "Input"
+
+slds_classes:
+  root: "slds-dueling-list"
+  elements:
+    - class: "slds-dueling-list__column"
+      description: "Column container for each list and button group"
+      purpose: "Organizes the two lists and control buttons in a flex layout"
+    - class: "slds-dueling-list__options"
+      description: "Bounding visual container for listbox of options"
+      purpose: "Contains the selectable options list with border and scrollable area"
+  modifiers:
+    - class: "slds-dueling-list__column_responsive"
+      description: "Responsive layout modifier for dueling picklist columns"
+      usage: "Applied to columns containing options to make them responsive and flexible"
+  states:
+    - class: "slds-is-selected"
+      description: "Selected state of a listbox option"
+      trigger: "When an option is selected (aria-selected='true')"
+    - class: "slds-is-grabbed"
+      description: "Grabbed state of a listbox option during drag"
+      trigger: "When an option is being dragged"
+    - class: "slds-is-disabled"
+      description: "Disabled state for the entire dueling picklist"
+      trigger: "When the component is not interactive"
+
+variants:
+  - name: "Base"
+    description: "Standard dueling picklist with two lists and move buttons"
+    classes: ["slds-dueling-list"]
+    usage_context: "Default dueling picklist implementation"
+    differences: "Two side-by-side lists with buttons to move items between them"
+  - name: "Responsive"
+    description: "Responsive dueling picklist that adapts to available space"
+    classes: ["slds-dueling-list", "slds-dueling-list__column_responsive"]
+    usage_context: "Use in narrow regions or responsive layouts"
+    differences: "Columns flex to available space, items truncate with ellipsis"
+
+lightning_component:
+  name: ""
+  url: "https://developer.salesforce.com/docs/component-library/overview/components"
+  mapping_notes: "No direct Lightning Base Component - use custom implementation with SLDS classes"
+
+accessibility:
+  keyboard_support:
+    - "Tab to navigate between lists and buttons"
+    - "Up/Down arrows to move focus and selection within a list"
+    - "Shift + Up/Down to extend selection"
+    - "Ctrl + Up/Down to move focus without changing selection"
+    - "Ctrl + Space to toggle selection on focused option"
+    - "Ctrl + A to select all options in a list"
+    - "Cmd/Ctrl + Left/Right to move selected items between lists"
+    - "Space to toggle Drag and Drop mode"
+    - "In Drag mode: Up/Down arrows move selected items within current list"
+  screen_reader:
+    - "List labels announced via aria-labelledby"
+    - "Operation instructions announced via aria-describedby"
+    - "Selected state announced for each option"
+    - "Drag and drop mode announced"
+  aria_attributes:
+    - "role='listbox' on each options container"
+    - "aria-multiselectable='true' on each listbox"
+    - "aria-selected on each option (true/false)"
+    - "aria-labelledby pointing to list label"
+    - "aria-describedby for operation instructions"
+    - "tabindex='0' on selected items, '-1' on others"
+    - "role='group' on form-element wrapper"
+    - "aria-labelledby on group pointing to group label ID"
+
+usage_guidelines:
+  when_to_use:
+    - "When users need to select multiple options from a large set"
+    - "For moving items between available and selected lists"
+    - "When reordering selected items is needed"
+    - "For complex multi-select scenarios"
+  when_not_to_use:
+    - "For single selection (use select or combobox)"
+    - "When only a few options exist (use checkboxes)"
+    - "In very constrained spaces"
+    - "When drag and drop is not supported"
+  best_practices:
+    - "Use group labels (fieldset/legend pattern) for accessibility"
+    - "Provide clear operation instructions"
+    - "Support both button and keyboard interactions"
+    - "Implement proper focus management"
+    - "Handle drag and drop gracefully with fallbacks"
+    - "Use responsive variant for narrow layouts"
+    - "Provide visual feedback for all interactions"
+  common_mistakes:
+    - "Not implementing proper ARIA listbox patterns"
+    - "Missing keyboard navigation support"
+    - "Inadequate focus management"
+    - "Not providing operation instructions"
+    - "Missing group labels for accessibility"
+
+code_examples:
+  - title: "Basic Dueling Picklist"
+    code: |
+      <div class="slds-form-element" role="group" aria-labelledby="dueling-picklist-label">
+        <div class="slds-form-element__label slds-form-element__legend" id="dueling-picklist-label">
+          Select Options
+        </div>
+        <div class="slds-form-element__control">
+          <div class="slds-dueling-list">
+            <div class="slds-dueling-list__column">
+              <span class="slds-form-element__label">Available</span>
+              <div class="slds-dueling-list__options" role="listbox" aria-multiselectable="true" aria-labelledby="available-label">
+                <div role="option" aria-selected="false" tabindex="0">Option 1</div>
+                <div role="option" aria-selected="false" tabindex="-1">Option 2</div>
+                <div role="option" aria-selected="false" tabindex="-1">Option 3</div>
+              </div>
+            </div>
+            <div class="slds-dueling-list__column">
+              <button class="slds-button slds-button_neutral">Move Right</button>
+              <button class="slds-button slds-button_neutral">Move Left</button>
+            </div>
+            <div class="slds-dueling-list__column">
+              <span class="slds-form-element__label">Selected</span>
+              <div class="slds-dueling-list__options" role="listbox" aria-multiselectable="true" aria-labelledby="selected-label">
+                <div role="option" aria-selected="false" tabindex="0">Option 4</div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    description: "Basic dueling picklist with two lists and move buttons"
+  - title: "Responsive Dueling Picklist"
+    code: |
+      <div class="slds-form-element" role="group" aria-labelledby="responsive-picklist-label">
+        <div class="slds-form-element__label slds-form-element__legend" id="responsive-picklist-label">
+          Select Options
+        </div>
+        <div class="slds-form-element__control">
+          <div class="slds-dueling-list">
+            <div class="slds-dueling-list__column slds-dueling-list__column_responsive">
+              <span class="slds-form-element__label">Available</span>
+              <div class="slds-dueling-list__options" role="listbox" aria-multiselectable="true">
+                <div role="option" aria-selected="false" tabindex="0">Option 1</div>
+                <div role="option" aria-selected="false" tabindex="-1">Option 2</div>
+              </div>
+            </div>
+            <div class="slds-dueling-list__column">
+              <button class="slds-button slds-button_neutral">Move Right</button>
+              <button class="slds-button slds-button_neutral">Move Left</button>
+            </div>
+            <div class="slds-dueling-list__column slds-dueling-list__column_responsive">
+              <span class="slds-form-element__label">Selected</span>
+              <div class="slds-dueling-list__options" role="listbox" aria-multiselectable="true">
+                <div role="option" aria-selected="false" tabindex="0">Option 3</div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    description: "Responsive dueling picklist that adapts to available space"
+
+styling_hooks: []
+
+dependencies:
+  css_files: ["dueling-picklist.css", "form-element.css", "listbox.css", "button.css"]
+  javascript:
+    - "Listbox selection management"
+    - "Item movement between lists"
+    - "Drag and drop functionality (optional)"
+    - "Keyboard navigation"
+    - "Focus management"
+  icons: []
+  other_components: ["form-element", "listbox", "button"]
+
+related_components:
+  - name: "Listbox"
+    relationship: "depends-on"
+    description: "ARIA listbox component used for each list"
+  - name: "Select"
+    relationship: "alternative"
+    description: "For single selection scenarios"
+  - name: "Multi-Select"
+    relationship: "similar"
+    description: "Alternative multi-select component"
+
+references:
+  official_docs: "https://v1.lightningdesignsystem.com/components/dueling-picklist/"
+  design_guidelines: "https://v1.lightningdesignsystem.com/components/dueling-picklist/"
+metadata:
+  version: "1.0.0"
+  last_updated: "2025-01-15"
+  author: "SLDS Documentation Team"
+  slds_version: "2.27.2"
+  review_status: "complete"
+  source: "official-slds"
+  notes: "Created from official SLDS documentation and design-system-internal source code with CSS selector annotations. Follows ARIA listbox practices for accessibility."
+