{
  "_copyright": "Copyright (c) 2026, Salesforce, Inc., All rights reserved. For full license text, see the LICENSE.txt file",
  "$schema": "https://slds.lightningdesignsystem.com/schemas/uif-foundation.v1.json",
  "apiVersion": "1.0.0",
  "name": "ColorPicker",
  "description": "Fully featured color picker, with swatches and a custom color config",
  "structure": {
    "name": "root",
    "restrict": [
      "div"
    ],
    "description": "Fully featured color picker, with swatches and a custom color config",
    "children": [
      {
        "name": "summary",
        "restrict": [
          "div"
        ],
        "description": "'Summary' element for color selection.",
        "children": [
          {
            "name": "summaryLabel",
            "restrict": [
              "label"
            ],
            "description": "Label for summary input"
          },
          {
            "name": "summaryControl",
            "restrict": [
              "div"
            ],
            "description": "Form-element control wrapper around the trigger button and hex input",
            "children": [
              {
                "name": "summaryButton",
                "restrict": [
                  "button"
                ],
                "description": "Button that toggles the Color Picker Selector"
              },
              {
                "name": "swatch",
                "restrict": [
                  "span"
                ],
                "description": "A swatch"
              },
              {
                "name": "swatchAssistiveText",
                "restrict": [
                  "span"
                ],
                "description": "Assistive-text label describing the swatch's current color"
              },
              {
                "name": "summaryButtonIcon",
                "restrict": [
                  "svg"
                ],
                "description": "Caret icon rendered inside the trigger button"
              },
              {
                "name": "summaryButtonIconUse",
                "restrict": [
                  "use"
                ],
                "description": "Use element referencing the caret sprite"
              },
              {
                "name": "summaryButtonAssistiveText",
                "restrict": [
                  "span"
                ],
                "description": "Assistive text announcing the trigger's action and current color"
              },
              {
                "name": "summaryInput",
                "restrict": [
                  "div"
                ],
                "description": "Input field for summary UI",
                "children": [
                  {
                    "name": "summaryInputField",
                    "restrict": [
                      "input"
                    ],
                    "description": "Hex color value text input"
                  }
                ]
              },
              {
                "name": "summaryError",
                "restrict": [
                  "p"
                ],
                "description": "Validation error message for the summary hex input",
                "renderWhen": {
                  "prop": "hasError",
                  "eq": "true"
                }
              }
            ]
          }
        ]
      },
      {
        "name": "dropdown",
        "restrict": [
          "section"
        ],
        "description": "The selector subcomponent. Extends upon a .slds-popover",
        "renderWhen": {
          "prop": "open",
          "eq": "true"
        },
        "children": [
          {
            "name": "dropdownBody",
            "restrict": [
              "div"
            ],
            "description": "Popover body wrapper",
            "children": [
              {
                "name": "dropdownMedia",
                "restrict": [
                  "div"
                ],
                "description": "Media object that lays out the dropdown content",
                "children": [
                  {
                    "name": "dropdownMediaBody",
                    "restrict": [
                      "div"
                    ],
                    "description": "Media body that contains the tabs or single-mode content",
                    "children": [
                      {
                        "name": "tabs",
                        "restrict": [
                          "div"
                        ],
                        "description": "Default + Custom tabs container (present in the base layout)",
                        "renderWhen": {
                          "prop": "mode",
                          "eq": "base"
                        },
                        "children": [
                          {
                            "name": "tabsNav",
                            "restrict": [
                              "ul"
                            ],
                            "description": "Tablist of Default and Custom tabs",
                            "children": [
                              {
                                "name": "tabItem",
                                "restrict": [
                                  "li"
                                ],
                                "description": "Tablist item (Default or Custom)",
                                "children": [
                                  {
                                    "name": "tabLink",
                                    "restrict": [
                                      "a"
                                    ],
                                    "description": "Anchor acting as the tab trigger"
                                  }
                                ]
                              }
                            ]
                          },
                          {
                            "name": "tabPanelDefault",
                            "restrict": [
                              "div"
                            ],
                            "description": "Tabpanel containing the preset swatch grid"
                          },
                          {
                            "name": "tabPanelCustom",
                            "restrict": [
                              "div"
                            ],
                            "description": "Tabpanel containing the custom color tools"
                          }
                        ]
                      },
                      {
                        "name": "swatches",
                        "restrict": [
                          "ul"
                        ],
                        "description": "Swatch container",
                        "children": [
                          {
                            "name": "swatchItem",
                            "restrict": [
                              "li"
                            ],
                            "description": "Color Picker swatch",
                            "children": [
                              {
                                "name": "swatchTrigger",
                                "restrict": [
                                  "a"
                                ],
                                "description": "Anchor that selects this swatch's color",
                                "children": [
                                  {
                                    "name": "swatchSample",
                                    "restrict": [
                                      "span"
                                    ],
                                    "description": "A swatch"
                                  },
                                  {
                                    "name": "swatchSampleAssistiveText",
                                    "restrict": [
                                      "span"
                                    ],
                                    "description": "Assistive text announcing the swatch's hex value"
                                  }
                                ]
                              }
                            ]
                          }
                        ]
                      },
                      {
                        "name": "custom",
                        "restrict": [
                          "div"
                        ],
                        "description": "Custom picker selection container",
                        "children": [
                          {
                            "name": "customInstructions",
                            "restrict": [
                              "p"
                            ],
                            "description": "Assistive-text instructions for keyboard users of the custom range"
                          },
                          {
                            "name": "customRange",
                            "restrict": [
                              "div"
                            ],
                            "description": "Custom picker range element",
                            "children": [
                              {
                                "name": "customRangeIndicator",
                                "restrict": [
                                  "a"
                                ],
                                "description": "Draggable position indicator on the custom range surface",
                                "children": [
                                  {
                                    "name": "customRangeAssistiveText",
                                    "restrict": [
                                      "span"
                                    ],
                                    "description": "Assistive text announcing the currently selected hex value"
                                  }
                                ]
                              }
                            ]
                          },
                          {
                            "name": "hueAndPreview",
                            "restrict": [
                              "div"
                            ],
                            "description": "Container element for the hue slider and preview swatch",
                            "children": [
                              {
                                "name": "hueLabel",
                                "restrict": [
                                  "label"
                                ],
                                "description": "Assistive-text label for the hue slider"
                              },
                              {
                                "name": "hueSlider",
                                "restrict": [
                                  "input"
                                ],
                                "description": "The slide input that controls the hue"
                              },
                              {
                                "name": "huePreviewSwatch",
                                "restrict": [
                                  "span"
                                ],
                                "description": "A swatch",
                                "children": [
                                  {
                                    "name": "huePreviewAssistiveText",
                                    "restrict": [
                                      "span"
                                    ],
                                    "description": "Assistive text announcing the previewed hex value"
                                  }
                                ]
                              }
                            ]
                          },
                          {
                            "name": "customInputs",
                            "restrict": [
                              "div"
                            ],
                            "description": "The group of direct input elements",
                            "children": [
                              {
                                "name": "customInputHex",
                                "restrict": [
                                  "div"
                                ],
                                "description": "Hex input form-element",
                                "children": [
                                  {
                                    "name": "customInputHexLabel",
                                    "restrict": [
                                      "label"
                                    ],
                                    "description": "Label for the hex input"
                                  },
                                  {
                                    "name": "customInputHexControl",
                                    "restrict": [
                                      "div"
                                    ],
                                    "description": "Form-element control wrapping the hex input",
                                    "children": [
                                      {
                                        "name": "customInputHexField",
                                        "restrict": [
                                          "input"
                                        ],
                                        "description": "Hex text input"
                                      }
                                    ]
                                  }
                                ]
                              },
                              {
                                "name": "customInputRgb",
                                "restrict": [
                                  "div"
                                ],
                                "description": "RGB channel input form-element (R, G, or B)",
                                "children": [
                                  {
                                    "name": "customInputRgbLabel",
                                    "restrict": [
                                      "label"
                                    ],
                                    "description": "Label for the RGB channel input, wrapping an abbr element",
                                    "children": [
                                      {
                                        "name": "customInputRgbLabelAbbr",
                                        "restrict": [
                                          "abbr"
                                        ],
                                        "description": "Abbreviated channel name (R, G, B)"
                                      }
                                    ]
                                  },
                                  {
                                    "name": "customInputRgbControl",
                                    "restrict": [
                                      "div"
                                    ],
                                    "description": "Form-element control wrapping the RGB channel input",
                                    "children": [
                                      {
                                        "name": "customInputRgbField",
                                        "restrict": [
                                          "input"
                                        ],
                                        "description": "RGB channel text input"
                                      }
                                    ]
                                  }
                                ]
                              }
                            ]
                          },
                          {
                            "name": "customError",
                            "restrict": [
                              "p"
                            ],
                            "description": "Validation error message for the custom hex input",
                            "renderWhen": {
                              "prop": "hasError",
                              "eq": "true"
                            }
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "name": "footer",
            "restrict": [
              "footer"
            ],
            "description": "Popover footer hosting the Cancel and Done buttons",
            "children": [
              {
                "name": "footerActions",
                "restrict": [
                  "div"
                ],
                "description": "Footer for the Color Selector Picker",
                "children": [
                  {
                    "name": "footerCancelButton",
                    "restrict": [
                      "button"
                    ],
                    "description": "Cancel action button"
                  },
                  {
                    "name": "footerDoneButton",
                    "restrict": [
                      "button"
                    ],
                    "description": "Done action button"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "states": [
    {
      "name": "open",
      "type": "boolean",
      "aria": "aria-expanded",
      "description": "Whether the picker dropdown is open"
    },
    {
      "name": "value",
      "type": "enum",
      "description": "Selected color value (free-form hex/HSL string)"
    },
    {
      "name": "disabled",
      "type": "boolean",
      "aria": "aria-disabled",
      "description": "Whether the color picker is disabled"
    },
    {
      "name": "hasError",
      "type": "boolean",
      "description": "Whether the color picker is in an error state"
    },
    {
      "name": "mode",
      "type": "enum",
      "options": [
        "base",
        "predefined-only",
        "custom-only",
        "swatches-only"
      ],
      "description": "Which tools the picker exposes: base (preset + custom tabs), predefined-only, custom-only, or swatches-only"
    }
  ],
  "accessibility": {
    "requirements": [
      {
        "id": "color-name",
        "description": "Selected color should be announced by name when possible"
      },
      {
        "id": "dialog-role",
        "description": "The open dropdown is a dialog and must expose an accessible name (aria-label) and pointer to its body (aria-describedby)"
      },
      {
        "id": "swatch-list",
        "description": "Preset swatches are exposed as a listbox/menu of options; each option must announce its color value via assistive text"
      }
    ]
  }
}