[docs][joy] Improve the descriptions of props in API docs

docs/data/joy/customization/themed-components/themed-components.md

@@ -112,6 +112,62 @@ extendTheme({
 });
 ```
 
+### Extend colors
+
+The following code snippet illustrates how to provide additional colors to a component beyond `primary`, `success`, `info`, `danger`, `neutral`, and `warning`.
+
+Note that by creating new colors, you're automatically opting out of the [global variant feature](/joy-ui/main-features/global-variants/), which gives you fine-grained control over CSS properties like `color`, `background`, and `border`.
+
+The example below extends the Button colors to include `secondary` value:
+
+```js
+extendTheme({
+  components: {
+    JoyButton: {
+      styleOverrides: {
+        root: ({ ownerState, theme }) => ({
+          ...(ownerState.color === 'secondary' && {
+            color: theme.vars.palette.text.secondary,
+            backgroundColor: theme.vars.palette.background.level1,
+          }),
+        }),
+      },
+    },
+  },
+});
+```
+
+Once these values are defined as above, you can make use of them directly on instances of the Button component:
+
+```jsx
+<Button color="secondary">Secondary color</Button>
+<Button color="tertiary">Tertiary color</Button>
+```
+
+:::info
+To learn how to extend size properties, check out the [Extend sizes](#extend-sizes) section in this document.
+:::
+
+#### TypeScript
+
+Module augmentation is required to pass the values to the `color` prop of the component.
+
+The interface format is `{ComponentName}PropsColorOverrides`, which is the same for all Joy UI components:
+
+```tsx
+// This part could be declared in your theme file
+declare module '@mui/joy/Button' {
+  interface ButtonPropsColorOverrides {
+    secondary: true;
+    tertiary: true;
+  }
+}
+
+// typed-safe
+<Button color="secondary" />
+<Button color="tertiary" />
+```
+
 ### Extend sizes
 
 The following code snippet illustrates how to provide additional sizes to a component beyond `sm`, `md`, and `lg`.
@@ -157,7 +213,7 @@ Once these values are defined as above, you can make use of them directly on ins
 
 :::info
 The properties used for extending sizes should only relate to the density or the dimensions of the component.
-To learn how to extend color properties, check out the [Extend variants](#extend-variants) section in this document.
+To learn how to extend variant properties, check out the [Extend variants](#extend-variants) section in this document.
 :::
 
 #### TypeScript

docs/src/modules/components/ApiPage.js

@@ -176,7 +176,9 @@ export default function ApiPage(props) {
   const styleOverridesLink = isJoyComponent
     ? '/joy-ui/customization/themed-components/#style-overrides'
     : '/material-ui/customization/theme-components/#global-style-overrides';
-
+  const extendVariantsLink = isJoyComponent
+    ? '/joy-ui/customization/themed-components/#extend-variants'
+    : '';
   const {
     componentDescription,
     componentDescriptionToc = [],
@@ -185,6 +187,17 @@ export default function ApiPage(props) {
     slotDescriptions,
   } = descriptions[userLanguage];
   const description = t('api-docs.pageDescription').replace(/{{name}}/, componentName);
+  const slotExtraDescription = extendVariantsLink
+    ? t('api-docs.slotDescription').replace(/{{extendVariantsLink}}/, extendVariantsLink)
+    : '';
+  if (slotDescriptions && slotExtraDescription) {
+    Object.keys(slotDescriptions).forEach((slot) => {
+      if (slotDescriptions[slot].match(slotExtraDescription)) {
+        return;
+      }
+      slotDescriptions[slot] += ` ${slotExtraDescription}`;
+    });
+  }
 
   const source = filename
     .replace(/\/packages\/mui(-(.+?))?\/src/, (match, dash, pkg) => `@mui/${pkg}`)

docs/translations/api-docs-joy/alert/alert.json

@@ -1,13 +1,13 @@
 {
   "componentDescription": "",
   "propDescriptions": {
-    "color": "The color of the component. It supports those theme colors that make sense for this component.",
+    "color": "The color of the component. It supports those theme colors that make sense for this component. To learn how to add your own colors, check out <a href=\"/joy-ui/customization/themed-components/#extend-colors\">Themed components—Extend colors</a>.",
     "endDecorator": "Element placed after the children.",
     "role": "The ARIA role attribute of the element.",
-    "size": "The size of the component.",
+    "size": "The size of the component. To learn how to add custom sizes to the component, check out <a href=\"/joy-ui/customization/themed-components/#extend-sizes\">Themed components—Extend sizes</a>.",
     "startDecorator": "Element placed before the children.",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/getting-started/the-sx-prop/\">`sx` page</a> for more details.",
-    "variant": "The variant to use."
+    "variant": "The <a href=\"https://mui.com/joy-ui/main-features/global-variants/\">global variant</a> to use. To learn how to add your own variants, check out <a href=\"/joy-ui/customization/themed-components/#extend-variants\">Themed components—Extend variants</a>."
   },
   "classDescriptions": {},
   "slotDescriptions": {

docs/translations/api-docs-joy/aspect-ratio/aspect-ratio.json

@@ -2,13 +2,13 @@
   "componentDescription": "",
   "propDescriptions": {
     "children": "Used to render icon or text elements inside the AspectRatio if <code>src</code> is not set. This can be an element, or just a string.",
-    "color": "The color of the component. It supports those theme colors that make sense for this component.",
+    "color": "The color of the component. It supports those theme colors that make sense for this component. To learn how to add your own colors, check out <a href=\"/joy-ui/customization/themed-components/#extend-colors\">Themed components—Extend colors</a>.",
     "maxHeight": "The maximum calculated height of the element (not the CSS height).",
     "minHeight": "The minimum calculated height of the element (not the CSS height).",
     "objectFit": "The CSS object-fit value of the first-child.",
     "ratio": "The aspect-ratio of the element. The current implementation uses padding instead of the CSS aspect-ratio due to browser support. <a href=\"https://caniuse.com/?search=aspect-ratio\">https://caniuse.com/?search=aspect-ratio</a>",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/getting-started/the-sx-prop/\">`sx` page</a> for more details.",
-    "variant": "The variant to use."
+    "variant": "The <a href=\"https://mui.com/joy-ui/main-features/global-variants/\">global variant</a> to use. To learn how to add your own variants, check out <a href=\"/joy-ui/customization/themed-components/#extend-variants\">Themed components—Extend variants</a>."
   },
   "classDescriptions": {},
   "slotDescriptions": {

docs/translations/api-docs-joy/autocomplete-listbox/autocomplete-listbox.json

@@ -1,11 +1,11 @@
 {
   "componentDescription": "",
   "propDescriptions": {
-    "color": "The color of the component. It supports those theme colors that make sense for this component.",
+    "color": "The color of the component. It supports those theme colors that make sense for this component. To learn how to add your own colors, check out <a href=\"/joy-ui/customization/themed-components/#extend-colors\">Themed components—Extend colors</a>.",
     "component": "The component used for the root node. Either a string to use a HTML element or a component.",
-    "size": "The size of the component (affect other nested list* components).",
+    "size": "The size of the component (affect other nested list* components). To learn how to add custom sizes to the component, check out <a href=\"/joy-ui/customization/themed-components/#extend-sizes\">Themed components—Extend sizes</a>.",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/getting-started/the-sx-prop/\">`sx` page</a> for more details.",
-    "variant": "The variant to use."
+    "variant": "The <a href=\"https://mui.com/joy-ui/main-features/global-variants/\">global variant</a> to use. To learn how to add your own variants, check out <a href=\"/joy-ui/customization/themed-components/#extend-variants\">Themed components—Extend variants</a>."
   },
   "classDescriptions": {}
 }

docs/translations/api-docs-joy/autocomplete-option/autocomplete-option.json

@@ -1,10 +1,10 @@
 {
   "componentDescription": "",
   "propDescriptions": {
-    "color": "The color of the component. It supports those theme colors that make sense for this component.",
+    "color": "The color of the component. It supports those theme colors that make sense for this component. To learn how to add your own colors, check out <a href=\"/joy-ui/customization/themed-components/#extend-colors\">Themed components—Extend colors</a>.",
     "component": "The component used for the root node. Either a string to use a HTML element or a component.",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/getting-started/the-sx-prop/\">`sx` page</a> for more details.",
-    "variant": "The variant to use."
+    "variant": "The <a href=\"https://mui.com/joy-ui/main-features/global-variants/\">global variant</a> to use. To learn how to add your own variants, check out <a href=\"/joy-ui/customization/themed-components/#extend-variants\">Themed components—Extend variants</a>."
   },
   "classDescriptions": {}
 }

docs/translations/api-docs-joy/autocomplete/autocomplete.json

@@ -8,7 +8,7 @@
     "clearIcon": "The icon to display in place of the default clear icon.",
     "clearText": "Override the default text for the <em>clear</em> icon button.<br>For localization purposes, you can use the provided <a href=\"/material-ui/guides/localization/\">translations</a>.",
     "closeText": "Override the default text for the <em>close popup</em> icon button.<br>For localization purposes, you can use the provided <a href=\"/material-ui/guides/localization/\">translations</a>.",
-    "color": "The color of the component. It supports those theme colors that make sense for this component.",
+    "color": "The color of the component. It supports those theme colors that make sense for this component. To learn how to add your own colors, check out <a href=\"/joy-ui/customization/themed-components/#extend-colors\">Themed components—Extend colors</a>.",
     "defaultValue": "The default value. Use when the component is not controlled.",
     "disableClearable": "If <code>true</code>, the input can&#39;t be cleared.",
     "disabled": "If <code>true</code>, the component is disabled.",
@@ -45,12 +45,12 @@
     "renderOption": "Render the option, use <code>getOptionLabel</code> by default.<br><br><strong>Signature:</strong><br><code>function(props: object, option: T, state: object) =&gt; ReactNode</code><br><em>props:</em> The props to apply on the li element.<br><em>option:</em> The option to render.<br><em>state:</em> The state of the component.",
     "renderTags": "Render the selected value.<br><br><strong>Signature:</strong><br><code>function(value: Array&lt;T&gt;, getTagProps: function, ownerState: object) =&gt; ReactNode</code><br><em>value:</em> The <code>value</code> provided to the component.<br><em>getTagProps:</em> A tag props getter.<br><em>ownerState:</em> The state of the Autocomplete component.",
     "required": "If <code>true</code>, the <code>input</code> element is required. The prop defaults to the value (<code>false</code>) inherited from the parent FormControl component.",
-    "size": "The size of the component.",
+    "size": "The size of the component. To learn how to add custom sizes to the component, check out <a href=\"/joy-ui/customization/themed-components/#extend-sizes\">Themed components—Extend sizes</a>.",
     "startDecorator": "Leading adornment for this input.",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/getting-started/the-sx-prop/\">`sx` page</a> for more details.",
     "type": "Type of the <code>input</code> element. It should be <a href=\"https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types\">a valid HTML5 input type</a>.",
     "value": "The value of the autocomplete.<br>The value must have reference equality with the option in order to be selected. You can customize the equality behavior with the <code>isOptionEqualToValue</code> prop.",
-    "variant": "The variant to use."
+    "variant": "The <a href=\"https://mui.com/joy-ui/main-features/global-variants/\">global variant</a> to use. To learn how to add your own variants, check out <a href=\"/joy-ui/customization/themed-components/#extend-variants\">Themed components—Extend variants</a>."
   },
   "classDescriptions": {},
   "slotDescriptions": {

docs/translations/api-docs-joy/avatar-group/avatar-group.json

@@ -2,11 +2,11 @@
   "componentDescription": "",
   "propDescriptions": {
     "children": "Used to render icon or text elements inside the AvatarGroup if <code>src</code> is not set. This can be an element, or just a string.",
-    "color": "The color of the component. It supports those theme colors that make sense for this component.",
+    "color": "The color of the component. It supports those theme colors that make sense for this component. To learn how to add your own colors, check out <a href=\"/joy-ui/customization/themed-components/#extend-colors\">Themed components—Extend colors</a>.",
     "component": "The component used for the root node. Either a string to use a HTML element or a component.",
-    "size": "The size of the component. It accepts theme values between &#39;sm&#39; and &#39;lg&#39;.",
+    "size": "The size of the component. It accepts theme values between &#39;sm&#39; and &#39;lg&#39;. To learn how to add custom sizes to the component, check out <a href=\"/joy-ui/customization/themed-components/#extend-sizes\">Themed components—Extend sizes</a>.",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/getting-started/the-sx-prop/\">`sx` page</a> for more details.",
-    "variant": "The variant to use."
+    "variant": "The <a href=\"https://mui.com/joy-ui/main-features/global-variants/\">global variant</a> to use. To learn how to add your own variants, check out <a href=\"/joy-ui/customization/themed-components/#extend-variants\">Themed components—Extend variants</a>."
   },
   "classDescriptions": {}
 }

docs/translations/api-docs-joy/avatar/avatar.json

@@ -3,12 +3,12 @@
   "propDescriptions": {
     "alt": "Used in combination with <code>src</code> or <code>srcSet</code> to provide an alt attribute for the rendered <code>img</code> element.",
     "children": "Used to render icon or text elements inside the Avatar if <code>src</code> is not set. This can be an element, or just a string.",
-    "color": "The color of the component. It supports those theme colors that make sense for this component.",
-    "size": "The size of the component. It accepts theme values between &#39;sm&#39; and &#39;lg&#39;.",
+    "color": "The color of the component. It supports those theme colors that make sense for this component. To learn how to add your own colors, check out <a href=\"/joy-ui/customization/themed-components/#extend-colors\">Themed components—Extend colors</a>.",
+    "size": "The size of the component. It accepts theme values between &#39;sm&#39; and &#39;lg&#39;. To learn how to add custom sizes to the component, check out <a href=\"/joy-ui/customization/themed-components/#extend-sizes\">Themed components—Extend sizes</a>.",
     "src": "The <code>src</code> attribute for the <code>img</code> element.",
     "srcSet": "The <code>srcSet</code> attribute for the <code>img</code> element. Use this attribute for responsive image display.",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/getting-started/the-sx-prop/\">`sx` page</a> for more details.",
-    "variant": "The variant to use."
+    "variant": "The <a href=\"https://mui.com/joy-ui/main-features/global-variants/\">global variant</a> to use. To learn how to add your own variants, check out <a href=\"/joy-ui/customization/themed-components/#extend-variants\">Themed components—Extend variants</a>."
   },
   "classDescriptions": {},
   "slotDescriptions": {

docs/translations/api-docs-joy/badge/badge.json

@@ -5,13 +5,13 @@
     "badgeContent": "The content rendered within the badge.",
     "badgeInset": "The inset of the badge. Support shorthand syntax as described in <a href=\"https://developer.mozilla.org/en-US/docs/Web/CSS/inset\">https://developer.mozilla.org/en-US/docs/Web/CSS/inset</a>.",
     "children": "The badge will be added relative to this node.",
-    "color": "The color of the component. It supports those theme colors that make sense for this component.",
+    "color": "The color of the component. It supports those theme colors that make sense for this component. To learn how to add your own colors, check out <a href=\"/joy-ui/customization/themed-components/#extend-colors\">Themed components—Extend colors</a>.",
     "invisible": "If <code>true</code>, the badge is invisible.",
     "max": "Max count to show.",
     "showZero": "Controls whether the badge is hidden when <code>badgeContent</code> is zero.",
-    "size": "The size of the component.",
+    "size": "The size of the component. To learn how to add custom sizes to the component, check out <a href=\"/joy-ui/customization/themed-components/#extend-sizes\">Themed components—Extend sizes</a>.",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/getting-started/the-sx-prop/\">`sx` page</a> for more details.",
-    "variant": "The variant to use."
+    "variant": "The <a href=\"https://mui.com/joy-ui/main-features/global-variants/\">global variant</a> to use. To learn how to add your own variants, check out <a href=\"/joy-ui/customization/themed-components/#extend-variants\">Themed components—Extend variants</a>."
   },
   "classDescriptions": {},
   "slotDescriptions": {

docs/translations/api-docs-joy/breadcrumbs/breadcrumbs.json

@@ -3,7 +3,7 @@
   "propDescriptions": {
     "children": "The content of the component.",
     "separator": "Custom separator node.",
-    "size": "The size of the component. It accepts theme values between 'sm' and 'lg'.",
+    "size": "The size of the component. It accepts theme values between &#39;sm&#39; and &#39;lg&#39;. To learn how to add custom sizes to the component, check out <a href=\"/joy-ui/customization/themed-components/#extend-sizes\">Themed components—Extend sizes</a>.",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/getting-started/the-sx-prop/\">`sx` page</a> for more details."
   },
   "classDescriptions": {},