@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/applying-slds/metadata/blueprints/components/prompt.yaml

@@ -0,0 +1,126 @@
+name: Prompt
+description: A prompt is a modal dialog that asks the user to confirm an action or provide input. It typically contains a
+  question or message, along with action buttons for the user to respond.
+category: Overlay
+slds_classes:
+  root: ''
+  elements: []
+  modifiers: []
+  states:
+  - class: slds-is-open
+    description: Open state for prompt modal
+    trigger: When prompt is visible
+  - class: slds-is-disabled
+    description: Disabled state for prompt actions
+    trigger: When prompt actions are not interactive
+variants:
+- name: Base
+  description: Standard prompt modal dialog
+  classes: []
+  usage_context: Default prompt implementation
+  differences: Modal dialog with header, body, and footer sections
+lightning_component:
+  name: lightning-modal
+  url: https://developer.salesforce.com/docs/component-library/bundle/lightning-modal
+  mapping_notes: Lightning modal can be configured as a prompt with appropriate content and actions
+accessibility:
+  keyboard_support:
+  - Tab to navigate between focusable elements
+  - Shift+Tab to navigate backwards
+  - Escape to close the prompt
+  - Enter to confirm (when appropriate)
+  screen_reader:
+  - Prompt title announced
+  - Prompt content announced
+  - Action buttons announced
+  - Close button announced
+  aria_attributes:
+  - role='dialog' or 'alertdialog' on prompt container
+  - aria-labelledby pointing to prompt title
+  - aria-describedby pointing to prompt content
+  - aria-modal='true' on dialog
+  - aria-label on close button
+  - Focus trap within modal
+usage_guidelines:
+  when_to_use:
+  - When user confirmation is required before an action
+  - For destructive actions that need confirmation
+  - When user input is needed in a modal context
+  - For important decisions that require user attention
+  when_not_to_use:
+  - For simple informational messages (use alerts)
+  - For non-critical confirmations (use inline confirmations)
+  - When action can be easily undone
+  - For frequent, repetitive confirmations
+  best_practices:
+  - Use clear, concise messaging
+  - Provide specific action button labels
+  - Make destructive actions clearly distinguishable
+  - Ensure proper focus management
+  - Provide keyboard shortcuts for common actions
+  - Use appropriate dialog role (dialog vs alertdialog)
+  - Include a way to dismiss (close button or cancel)
+  common_mistakes:
+  - Overusing prompts for non-critical actions
+  - Unclear or vague messaging
+  - Missing keyboard navigation
+  - Not trapping focus within modal
+  - Missing ARIA attributes
+  - No way to dismiss the prompt
+code_examples:
+- title: Basic Prompt
+  code: "<div class=\"slds-is-open\" role=\"dialog\" aria-labelledby=\"prompt-title\" aria-describedby=\"prompt-content\"\
+    \ aria-modal=\"true\">\n      <div class=\"\">\n        <h2 id=\"prompt-title\" class=\"slds-text-heading_medium\">Confirm\
+    \ Action</h2>\n        <button class=\"slds-button slds-button_icon slds-button_icon-small\" aria-label=\"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        </button>\n      </div>\n      <div class=\"\" id=\"prompt-content\">\n        <p>Are\
+    \ you sure you want to perform this action?</p>\n      </div>\n      <div class=\"\">\n        <button class=\"slds-button\
+    \ slds-button_neutral\">Cancel</button>\n        <button class=\"slds-button slds-button_brand\">Confirm</button>\n  \
+    \    </div>\n      </div>\n"
+- title: Destructive Action Prompt
+  code: "<div class=\"slds-is-open\" role=\"alertdialog\" aria-labelledby=\"delete-title\" aria-describedby=\"delete-content\"\
+    \ aria-modal=\"true\">\n      <div class=\"\">\n        <h2 id=\"delete-title\" class=\"slds-text-heading_medium\">Delete\
+    \ Record</h2>\n        <button class=\"slds-button slds-button_icon slds-button_icon-small\" aria-label=\"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        </button>\n      </div>\n      <div class=\"\" id=\"delete-content\">\n        <p>This\
+    \ action cannot be undone. Are you sure you want to delete this record?</p>\n      </div>\n      <div class=\"\">\n  \
+    \      <button class=\"slds-button slds-button_neutral\">Cancel</button>\n        <button class=\"slds-button slds-button_destructive\"\
+    >Delete</button>\n      </div>\n      </div>\n"
+styling_hooks: []
+dependencies:
+  css_files:
+  - prompt.css
+  - modal.css
+  - button.css
+  javascript:
+  - Modal open/close functionality
+  - Focus trap management
+  - Backdrop/overlay handling
+  - Escape key handling
+  icons:
+  - utility:close
+  other_components:
+  - modal
+  - button
+related_components:
+- name: Modal
+  relationship: parent
+  description: Base modal component that prompt extends
+- name: Alert
+  relationship: alternative
+  description: For non-interactive messages
+- name: Popover
+  relationship: alternative
+  description: For lightweight overlays
+references:
+  official_docs: https://v1.lightningdesignsystem.com/components/prompt/
+  design_guidelines: https://v1.lightningdesignsystem.com/components/prompt/
+metadata:
+  version: 1.0.0
+  last_updated: '2025-11-12'
+  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. 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/publishers.yaml

@@ -0,0 +1,178 @@
+name: "Publishers"
+
+description: "A component for creating and publishing content, posts, or comments. Provides an input area with formatting options and action buttons for submitting user-generated content."
+
+category: "Complex Components"
+
+slds_classes:
+  root: "slds-publisher"
+  elements:
+    - class: "slds-publisher__input"
+      description: "Input area for content creation"
+      purpose: "Text input or textarea for user content"
+    - class: "slds-publisher__actions"
+      description: "Container for publisher actions"
+      purpose: "Holds submit and formatting buttons"
+    - class: "slds-publisher__toggle-visibility"
+      description: "Toggle element for publisher visibility"
+      purpose: "Controls visibility of publisher component"
+  modifiers: []
+  states:
+    - class: "slds-is-active"
+      description: "Active state for publisher"
+      trigger: "When publisher is expanded and ready for input"
+
+variants:
+  - name: "Base"
+    description: "Standard publisher for creating posts or comments"
+    classes: ["slds-publisher"]
+    usage_context: "Default publisher implementation"
+    differences: "Input area with action buttons for content creation"
+
+lightning_component:
+  name: ""
+  url: "https://developer.salesforce.com/docs/component-library/overview/components"
+  mapping_notes: "No direct Lightning Base Component - typically built with lightning-textarea and custom components"
+
+accessibility:
+  keyboard_support:
+    - "Tab to navigate between input and buttons"
+    - "Enter in input field may submit (depending on implementation)"
+    - "Escape to cancel/collapse publisher"
+    - "Keyboard shortcuts for formatting (if supported)"
+  screen_reader:
+    - "Input field label announced"
+    - "Character count announced (if present)"
+    - "Action button purposes announced"
+    - "Submit confirmation announced"
+  aria_attributes:
+    - "aria-label on input field"
+    - "aria-describedby for character limits or hints"
+    - "aria-disabled on submit when invalid"
+    - "role='textbox' on input area"
+
+usage_guidelines:
+  when_to_use:
+    - "For creating social posts or updates"
+    - "For commenting systems"
+    - "In collaboration or communication features"
+    - "When users need to create content"
+  when_not_to_use:
+    - "For simple form inputs (use form elements)"
+    - "When content creation isn't primary action"
+    - "For search inputs"
+    - "When rich text editing isn't needed"
+  best_practices:
+    - "Provide clear submit action button"
+    - "Show character limits if applicable"
+    - "Support basic text formatting"
+    - "Auto-save drafts when possible"
+    - "Provide cancel/clear option"
+    - "Handle empty submissions gracefully"
+  common_mistakes:
+    - "Missing cancel or clear option"
+    - "No character limit indication"
+    - "Poor mobile keyboard handling"
+    - "Not preserving draft content"
+    - "Unclear submit button state"
+
+code_examples:
+  - title: "Basic Publisher"
+    code: |
+      <div class="slds-publisher slds-is-active">
+        <label for="publisher-textarea" class="slds-assistive-text">Write a post</label>
+        <textarea id="publisher-textarea" class="slds-publisher__input slds-textarea" placeholder="What's on your mind?"></textarea>
+        <div class="slds-publisher__actions slds-grid slds-grid_align-spread">
+          <ul class="slds-grid">
+            <li>
+              <button class="slds-button slds-button_icon slds-button_icon-border slds-button_icon-small" title="Attach a file">
+                <svg class="slds-button__icon" aria-hidden="true">
+                  <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#attach"></use>
+                </svg>
+                <span class="slds-assistive-text">Attach a file</span>
+              </button>
+            </li>
+          </ul>
+          <button class="slds-button slds-button_brand">Post</button>
+        </div>
+      </div>
+    description: "Basic publisher with text input and post button"
+  - title: "Publisher with Formatting Options"
+    code: |
+      <div class="slds-publisher slds-is-active">
+        <label for="rich-publisher-textarea" class="slds-assistive-text">Write a post</label>
+        <textarea id="rich-publisher-textarea" class="slds-publisher__input slds-textarea" placeholder="Share your thoughts..."></textarea>
+        <div class="slds-publisher__actions slds-grid slds-grid_align-spread">
+          <ul class="slds-grid slds-grid_vertical-align-center">
+            <li>
+              <button class="slds-button slds-button_icon slds-button_icon-border slds-button_icon-small" title="Bold">
+                <svg class="slds-button__icon" aria-hidden="true">
+                  <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#bold"></use>
+                </svg>
+                <span class="slds-assistive-text">Bold</span>
+              </button>
+            </li>
+            <li>
+              <button class="slds-button slds-button_icon slds-button_icon-border slds-button_icon-small" title="Italic">
+                <svg class="slds-button__icon" aria-hidden="true">
+                  <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#italic"></use>
+                </svg>
+                <span class="slds-assistive-text">Italic</span>
+              </button>
+            </li>
+            <li>
+              <button class="slds-button slds-button_icon slds-button_icon-border slds-button_icon-small" title="Link">
+                <svg class="slds-button__icon" aria-hidden="true">
+                  <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#link"></use>
+                </svg>
+                <span class="slds-assistive-text">Insert link</span>
+              </button>
+            </li>
+          </ul>
+          <div class="slds-grid">
+            <button class="slds-button slds-button_neutral slds-m-right_x-small">Cancel</button>
+            <button class="slds-button slds-button_brand">Publish</button>
+          </div>
+        </div>
+      </div>
+    description: "Publisher with text formatting options and cancel button"
+
+styling_hooks: []
+
+dependencies:
+  css_files: ["publishers.css", "textarea.css", "button.css"]
+  javascript:
+    - "Input validation"
+    - "Character counting"
+    - "Submit handling"
+    - "Draft auto-save"
+  icons:
+    - "utility:attach"
+    - "utility:bold"
+    - "utility:italic"
+    - "utility:link"
+  other_components: ["textarea", "button"]
+
+related_components:
+  - name: "Feed"
+    relationship: "complementary"
+    description: "Displays published content from publisher"
+  - name: "Rich Text Editor"
+    relationship: "alternative"
+    description: "More advanced editing capabilities"
+  - name: "Textarea"
+    relationship: "contains"
+    description: "Input element within publisher"
+
+references:
+  official_docs: "https://v1.lightningdesignsystem.com/components/publishers/"
+
+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/radio-button-group.yaml

@@ -0,0 +1,172 @@
+name: "Radio Button Group"
+
+description: "A group of radio buttons that allows users to select a single option from a set of mutually exclusive choices. Radio button groups are used when only one option can be selected at a time."
+
+category: "Input"
+
+slds_classes:
+  root: "slds-radio_button-group"
+  elements:
+    - class: "slds-radio_button"
+      description: "Individual radio button within the group"
+      purpose: "Container for each radio option in the button group"
+    - class: "slds-radio_faux"
+      description: "Visual radio button replacement styled as a button"
+      purpose: "Custom-styled radio appearance that looks like a button"
+    - class: "slds-radio_button__label"
+      description: "Label element for the radio button"
+      purpose: "Provides clickable area and contains the radio faux element"
+  modifiers: []
+  states:
+    - class: "slds-has-error"
+      description: "Error state styling for the form element"
+      trigger: "When radio button group validation fails"
+    - class: "slds-is-disabled"
+      description: "Disabled state styling"
+      trigger: "When radio button group is not interactive"
+
+variants:
+  - name: "Base"
+    description: "Standard radio button group"
+    classes: ["slds-radio_button-group"]
+    usage_context: "Default radio button group implementation"
+    differences: "Group of radio buttons with shared border and styling, mutually exclusive selection"
+
+lightning_component:
+  name: "lightning-radio-group"
+  url: "https://developer.salesforce.com/docs/component-library/bundle/lightning-radio-group"
+  mapping_notes: "Direct mapping - Lightning component implements SLDS radio button group blueprint"
+
+accessibility:
+  keyboard_support:
+    - "Tab to navigate to the radio button group"
+    - "Arrow keys (Up/Down/Left/Right) to navigate between radio options"
+    - "Space to select the focused radio option"
+    - "Tab to move to next form element after selection"
+  screen_reader:
+    - "Fieldset legend announced as group label"
+    - "Radio button state announced (checked/unchecked)"
+    - "Label text read with each radio button"
+    - "Error messages associated and announced"
+  aria_attributes:
+    - "fieldset and legend for group semantics"
+    - "aria-describedby for error messages"
+    - "aria-invalid when validation fails"
+    - "aria-required for required radio groups"
+    - "role='radiogroup' on fieldset (if not using native fieldset)"
+
+usage_guidelines:
+  when_to_use:
+    - "When users need to select exactly one option from a set"
+    - "For mutually exclusive choices"
+    - "When options are closely related and benefit from visual grouping"
+    - "For preference selection, single-choice forms, or settings"
+  when_not_to_use:
+    - "When multiple options can be selected (use checkbox group)"
+    - "For binary choices (use single checkbox or toggle)"
+    - "When only two options exist (consider toggle or checkbox)"
+    - "For actions (use buttons instead)"
+  best_practices:
+    - "Use clear, descriptive legend text for the group"
+    - "Keep option labels short and concise"
+    - "Group related options logically"
+    - "Provide immediate visual feedback for selection"
+    - "Ensure adequate touch target size for mobile"
+    - "Use error states to indicate validation issues"
+    - "Always have one option selected by default when appropriate"
+  common_mistakes:
+    - "Using radio button group for multiple selections"
+    - "Making labels too long or unclear"
+    - "Not providing proper fieldset/legend structure"
+    - "Missing error state handling"
+    - "Inadequate spacing between buttons"
+    - "Not having a default selection when one is expected"
+
+code_examples:
+  - title: "Basic Radio Button Group"
+    code: |
+      <fieldset class="slds-form-element">
+        <legend class="slds-form-element__legend slds-form-element__label">
+          Select an Option
+        </legend>
+        <div class="slds-form-element__control">
+          <div class="slds-radio_button-group">
+            <span class="slds-button slds-radio_button">
+              <input type="radio" name="radio-group" id="radio-1" value="option1" />
+              <label class="slds-radio_button__label" for="radio-1">
+                <span class="slds-radio_faux">Option 1</span>
+              </label>
+            </span>
+            <span class="slds-button slds-radio_button">
+              <input type="radio" name="radio-group" id="radio-2" value="option2" />
+              <label class="slds-radio_button__label" for="radio-2">
+                <span class="slds-radio_faux">Option 2</span>
+              </label>
+            </span>
+            <span class="slds-button slds-radio_button">
+              <input type="radio" name="radio-group" id="radio-3" value="option3" />
+              <label class="slds-radio_button__label" for="radio-3">
+                <span class="slds-radio_faux">Option 3</span>
+              </label>
+            </span>
+          </div>
+        </div>
+      </fieldset>
+    description: "Basic radio button group with three mutually exclusive options"
+  - title: "Radio Button Group with Error State"
+    code: |
+      <fieldset class="slds-form-element slds-has-error">
+        <legend class="slds-form-element__legend slds-form-element__label">
+          <abbr class="slds-required" title="required">*</abbr> Select an Option
+        </legend>
+        <div class="slds-form-element__control">
+          <div class="slds-radio_button-group">
+            <span class="slds-button slds-radio_button">
+              <input type="radio" name="radio-error" id="radio-error-1" value="option1" aria-describedby="radio-error-message" />
+              <label class="slds-radio_button__label" for="radio-error-1">
+                <span class="slds-radio_faux">Option 1</span>
+              </label>
+            </span>
+            <span class="slds-button slds-radio_button">
+              <input type="radio" name="radio-error" id="radio-error-2" value="option2" />
+              <label class="slds-radio_button__label" for="radio-error-2">
+                <span class="slds-radio_faux">Option 2</span>
+              </label>
+            </span>
+          </div>
+        </div>
+        <div id="radio-error-message" class="slds-form-element__help">This field is required</div>
+      </fieldset>
+    description: "Radio button group with error state and validation message"
+
+styling_hooks: []
+
+dependencies:
+  css_files: ["radio-button-group.css", "form-element.css", "radio-button.css"]
+  javascript: []
+  icons: []
+  other_components: ["form-element", "radio-button"]
+
+related_components:
+  - name: "Radio Group"
+    relationship: "similar"
+    description: "Standard radio group with circular radio buttons"
+  - name: "Checkbox Button Group"
+    relationship: "alternative"
+    description: "For multiple selections instead of single selection"
+  - name: "Radio Button"
+    relationship: "similar"
+    description: "Individual radio button component"
+
+references:
+  official_docs: "https://v1.lightningdesignsystem.com/components/radio-button-group/"
+  design_guidelines: "https://v1.lightningdesignsystem.com/components/radio-button-group/"
+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."
+

package/skills/applying-slds/metadata/blueprints/components/radio-group.yaml

@@ -0,0 +1,112 @@
+name: Radio Group
+description: A collection of radio button options that allows users to select exactly one choice from a set of mutually exclusive
+  options.
+category: Input
+slds_classes:
+  root: slds-radio_button-group
+  elements:
+  - class: slds-radio_button
+    description: Individual radio button wrapper
+    purpose: Contains a single radio button and its label
+  - class: slds-radio_button__label
+    description: Label element for the radio button
+    purpose: Provides clickable area and describes the option
+  modifiers: []
+  states:
+  - class: slds-has-error
+    description: Error state styling
+    trigger: When radio group validation fails
+  - class: slds-is-disabled
+    description: Disabled state styling
+    trigger: When radio group is not interactive
+variants:
+- name: Base
+  description: Standard radio button group
+  classes:
+  - slds-radio_button-group
+  usage_context: Default radio group implementation
+  differences: Standard radio buttons with labels arranged vertically
+lightning_component:
+  name: lightning-radio-group
+  url: https://developer.salesforce.com/docs/component-library/bundle/lightning-radio-group
+  mapping_notes: Direct mapping - Lightning component implements SLDS radio group blueprint
+accessibility:
+  keyboard_support:
+  - Tab to enter the radio group
+  - Arrow keys to navigate between options
+  - Space to select highlighted option
+  - Tab to exit the radio group
+  screen_reader:
+  - Group purpose and current selection announced
+  - Individual option labels read clearly
+  - Required state communicated when applicable
+  aria_attributes:
+  - role='radiogroup' for the container
+  - aria-labelledby for group labeling
+  - aria-describedby for group help text
+  - aria-required when selection is mandatory
+  - aria-invalid when validation fails
+usage_guidelines:
+  when_to_use:
+  - For mutually exclusive options (only one selection allowed)
+  - When users must choose exactly one option
+  - For small sets of related options (2-7 choices)
+  - When all options should be visible simultaneously
+  when_not_to_use:
+  - For multiple selections (use checkbox group instead)
+  - For large sets of options (use select or combobox)
+  - When no selection is a valid choice initially
+  best_practices:
+  - Use clear, distinct option labels
+  - Arrange options in logical order
+  - Provide a default selection when appropriate
+  - Keep option labels concise
+  - Group related options together
+  common_mistakes:
+  - Using radio groups for multiple selections
+  - Too many options making selection difficult
+  - Unclear or ambiguous option labels
+  - Not providing a sensible default selection
+code_examples:
+- title: Basic Radio Group
+  code: "<fieldset class=\"slds-form-element\">\n      <legend class=\"slds-form-element__legend slds-form-element__label\"\
+    >\n        <abbr class=\"slds-required\" title=\"required\">* </abbr>Radio Group Label\n      </legend>\n      <div class=\"\
+    slds-form-element__control\">\n        <div class=\"slds-radio_button-group\">\n          <span class=\"slds-radio_button\"\
+    >\n            <input type=\"radio\" id=\"radio-1\" value=\"option1\" name=\"options\" />\n            <label class=\"\
+    slds-radio_button__label\" for=\"radio-1\">\n              <span class=\"\"></span>\n              <span class=\"slds-form-element__label\"\
+    >Option One</span>\n            </label>\n          </span>\n          <span class=\"slds-radio_button\">\n          \
+    \  <input type=\"radio\" id=\"radio-2\" value=\"option2\" name=\"options\" />\n            <label class=\"slds-radio_button__label\"\
+    \ for=\"radio-2\">\n              <span class=\"\"></span>\n              <span class=\"slds-form-element__label\">Option\
+    \ Two</span>\n            </label>\n          </span>\n          <span class=\"slds-radio_button\">\n            <input\
+    \ type=\"radio\" id=\"radio-3\" value=\"option3\" name=\"options\" />\n            <label class=\"slds-radio_button__label\"\
+    \ for=\"radio-3\">\n              <span class=\"\"></span>\n              <span class=\"slds-form-element__label\">Option\
+    \ Three</span>\n            </label>\n          </span>\n        </div>\n      </div>\n      </fieldset>\n"
+styling_hooks:
+- name: --slds-c-radio-color-border
+  description: Border color for radio buttons
+  category: color
+dependencies:
+  css_files:
+  - radio-group.css
+  - form-element.css
+  javascript: []
+  icons: []
+  other_components:
+  - form-element
+related_components:
+- name: Checkbox Group
+  relationship: alternative
+  description: For multiple selection scenarios
+- name: Select
+  relationship: alternative
+  description: For larger sets of mutually exclusive options
+- name: Button Group
+  relationship: alternative
+  description: Alternative visual treatment for option selection
+references:
+  official_docs: https://v1.lightningdesignsystem.com/components/radio-group/
+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.'