Explained the concepts of Kind extension

15/umbraco-cms/customizing/extending-overview/extension-kind.md

@@ -8,29 +8,29 @@ description: Learn how to use the Kind extension in your manifest files when ext
 This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.
 {% endhint %}
 
-Extension Manifest Kind enables declarations to be based upon a preset Manifest.
+The **Extension Manifest Kind** is used to declare a preset configuration that other extensions can inherit. It ensures maintainability and consistency when creating extensions for the Umbraco CMS backoffice. By using a Kind, developers can reuse predefined settings, which reduces redundancy across extensions.
 
-This is used for maintainability or to inherit existing features.
+When a Kind is applied, the extension's manifest inherits the fields defined in the Kind. This approach prevents the need to repeat configuration details across multiple extensions.
 
 ## Manifest Kind Declaration
 
-A Kind is utilized by declaring it in the `kind` field of a Manifest:
+A **Kind** is declared in the `kind` field of the manifest, which is part of the extension registration process. The declaration is linked to a specific extension type.
 
 ```typescript
 const manifest = {
-    type: 'headerApp',
-    kind: 'button',
+    type: 'headerApp', // The type of the extension
+    kind: 'button',  // The kind alias to inherit settings from
     ...
 };
 ```
 
-By declaring a kind, the Manifest will inherit fields of the defined Kind.
+By setting the `kind` field, the extension automatically inherits all properties associated with that **Kind**. This is useful when you want to standardize a component (like a button) across multiple extensions.
 
-A typical use case is a Kind that provides an element, but requires additional meta fields, to fulfill the needs of its element.
+## Using the Kind for Inheritance
 
-In the following example, a manifest using the type 'headerApp' utilizes the 'button' kind. This brings an element and requires some additional information as part of the meta object.
+A Kind not only defines the basic configuration but may also require additional metadata to fully configure the element or component.
 
-Adding the metadata provides the ability to use and configure existing functionality to a specific need.
+### Example: Using the Button Kind in a Header App
 
 ```typescript
 const manifest = {
@@ -46,10 +46,11 @@ const manifest = {
 };
 ```
 
-## Learn more
+In this example:
+
+- The `kind: 'button'` inherits all default settings from the **Button Kind**.
+- The `meta` object is added to configure additional properties, such as the button's label, icon, and the URL to open when clicked.
 
-Learn more about Kinds and how to create your own:
+The Kind allows you to extend existing functionality and tailor it to specific needs while maintaining consistency.
 
-{% content-ref url="extension-types/kind.md" %}
-Kind Extension Type
-{% endcontent-ref %}
+For a deeper dive into Kind and how to create your own, see the [Kind](extension-types/kind.md) article.

15/umbraco-cms/customizing/extending-overview/extension-types/kind.md

@@ -1,5 +1,5 @@
 ---
-description: A kind extension provides the preset for other extensions to use
+description: A kind extension provides the preset for other extensions to use.
 ---
 
 # Kind
@@ -8,56 +8,86 @@ description: A kind extension provides the preset for other extensions to use
 This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.
 {% endhint %}
 
-A kind is matched with a specific type. When another extension uses that type and kind it will inherit the preset manifest of the kind extension.
+A Kind is a preset configuration that can be inherited by extensions to ensure consistency and reduce redundancy. It defines a set of default properties or behaviors that extensions can adopt, making it easier to maintain and configure extensions that share similar functionality.
 
-The registration of Kinds is done in the same manner as the registration of other extensions. But the format of it is different. Let's take a look at an example of how to implement the `Kind registration` for a [**Header App**](../extension-types/header-apps.md) **Button Kind**.
+A Kind is always linked to a specific extension type. Extensions using the same type and referencing a Kind automatically inherit its settings, ensuring uniformity across different extensions.
 
-## Understanding the Kind Extension
+## Benefits of Using a Kind
 
-The root properties of this object define the `Kind registration`. Then the manifest property holds the preset for the extension using this kind to be based upon. This object can hold the property values that make sense for the Kind.
+- Reduces redundancy – Common settings are defined once and reused across extensions.
+- Ensures consistency – Extensions using the same Kind follow a standardized structure and behavior.
+- Simplifies extension definitions – Extensions inherit predefined properties, reducing manual configuration.
 
-```typescript
-...
+## Kind Registration
+
+To register a Kind, use the same method as other extensions. The key properties that define a Kind registration are:
+
+- `type`: Always set to `kind`.
+- `alias`: A unique identifier for the Kind.
+- `matchType`: Specifies the extension type that the Kind applies to.
+- `matchKind`: Defines the Kind alias, which extensions must reference.
+- `manifest`: Contains the preset values that extensions will inherit.
 
+### Example: Registering a Button Kind for Header Apps
+
+The following example shows how to register a Button Kind for [**Header Apps**](../extension-types/header-apps.md). This kind provides a preset configuration for a button element that can be reused by other Header App extensions.
+
+```typescript
 const manifest: ManifestKind = {
 	type: 'kind',
-	alias: 'Umb.Kind.MyButtonKind',
-	matchType: 'headerApp',
-	matchKind: 'button',
+	alias: 'Umb.Kind.MyButtonKind', // Unique alias for the Kind
+	matchType: 'headerApp', // Applies to Header App extensions
+	matchKind: 'button', // Defines the Kind alias
 	manifest: {
-		...
+		// Add default properties for the 'button' Kind
+    	elementName: 'umb-header-app-button',
 	},
 };
-
-...
 ```
 
-For the kind to be used, it needs to match up with the registration of the extension using it. This happens when the extension uses a type, which matches the value of `matchType` of the Kind. As well the extension has to utilize that kind, by setting the value of `kind` to the value of `matchKind` the Kind.
+In this example:
 
-```typescript
-...
+- `type` is set to 'kind' to register it as a Kind extension.
+- `matchType` is 'headerApp', specifying that this Kind is for Header App extensions.
+- `matchKind` is 'button', which is the alias of the Kind.
+- The `manifest` contains default properties like elementName that extensions using this Kind will inherit.
+
+## Using the Kind in Other Extensions
 
+To use the Kind in other extensions, the extension must reference it by setting the `type` and `kind` properties. The extension will automatically inherit the Kind's properties.
+
+### Example: Header App Extension Using the Button Kind
+
+```typescript
 const manifest = {
-	type: 'headerApp',
-	kind: 'button',
-	...
+	type: 'headerApp', // Extension type
+	kind: 'button', // References the 'button' Kind
+	name: 'My Header App Example',
+	alias: 'My.HeaderApp.Example',
+	meta: {
+		label: 'My Example',
+		icon: 'icon-home',
+		href: '/some/path/to/open/when/clicked',
+  },
 };
 
-...
+extensionRegistry.register(manifest);
 ```
 
-## Kind example
+In this example, the Header App extension uses the `kind: 'button'`, meaning it inherits the `elementName` defined in the Button Kind. The extension can still add custom properties (like metadata in this case) to further customize the behavior or appearance.
+
+## Kind Example
 
-In the following example, a kind is registered. This kind provides a default element for extensions utilizing this kind.
+Here’s an example of how to register and use the Button Kind in a Header App extension:
 
 ```typescript
 import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
 
 const manifest: UmbExtensionManifest = {
   type: 'kind',
-  alias: 'Umb.Kind.MyButtonKind',
-  matchType: 'headerApp',
-  matchKind: 'button',
+  alias: 'Umb.Kind.MyButtonKind',  // Alias for the Kind
+  matchType: 'headerApp', // Extension type the Kind applies to
+  matchKind: 'button',  // Defines the Kind alias
   manifest: {
     elementName: 'umb-header-app-button',
   },
@@ -66,16 +96,16 @@ const manifest: UmbExtensionManifest = {
 umbExtensionsRegistry.register(manifest);
 ```
 
-This enables other extensions to use this kind and inherit the manifest properties defined in the kind.
+This code registers the Button Kind, so other Header App extensions using `type: 'headerApp'` and `kind: 'button'` will inherit the preset `elementName: 'umb-header-app-button'`.
 
-In this example a **Header App** is registered without defining an element, this is possible because the registration inherits the elementName from the kind.
+Now, another Header App extension can be created without defining `elementName`, as it will automatically inherit it from the Kind:
 
 ```typescript
 import { extensionRegistry } from '@umbraco-cms/extension-registry';
 
 const manifest = {
-	type: 'headerApp',
-	kind: 'button',
+	type: 'headerApp', // Extension type
+	kind: 'button',  // References the 'button' Kind
 	name: 'My Header App Example',
 	alias: 'My.HeaderApp.Example',
 	meta: {
@@ -87,3 +117,7 @@ const manifest = {
 
 extensionRegistry.register(manifest);
 ```
+
+By referencing the Kind, the extension inherits shared properties like `elementName`, ensuring consistency and reducing redundancy across extensions. This method also makes it easier to update configurations across multiple extensions.
+
+By using Kinds, you can create reusable, standardized configurations for extensions, helping to streamline development, ensure consistency, and reduce duplication. Understanding how to register and reference Kinds effectively will enhance the maintainability of your Umbraco extensions.