Updating docs and examples for tag component (#5379)

* tag: deprecation kind note

* updating docs

* next link

Author: DianaSuvorova

documentation-site/examples/tag/kinds.tsx

@@ -5,11 +5,16 @@ export default function Scenario() {
   return (
     <React.Fragment>
       {[
-        KIND.primary,
-        KIND.accent,
-        KIND.positive,
-        KIND.negative,
-        KIND.warning,
+        KIND.gray,
+        KIND.blue,
+        KIND.green,
+        KIND.red,
+        KIND.yellow,
+        KIND.orange,
+        KIND.purple,
+        KIND.magenta,
+        KIND.teal,
+        KIND.lime,
       ].map((kind) => (
         <div>
           <Tag

documentation-site/examples/tag/primitive.tsx

@@ -4,7 +4,6 @@ import Exports from "../../components/exports";
 
 import Basic from "examples/tag/basic.tsx";
 import Hierarchy from "examples/tag/variants.tsx";
-import Primitive from "examples/tag/primitive.tsx";
 import Kinds from "examples/tag/kinds.tsx";
 import Size from "examples/tag/size.tsx";
 import NonClickable from "examples/tag/non-clickable.tsx";
@@ -16,6 +15,7 @@ import CustomColor from "examples/tag/custom-color.tsx";
 
 import { Tag } from "baseui/tag";
 import * as TagExports from "baseui/tag";
+import { Notification, KIND as NOTIFICATION_KIND } from "baseui/notification";
 
 import Yard from "../../components/yard/index";
 import tagYardConfig from "../../components/yard/config/tag";
@@ -38,17 +38,29 @@ Compact UI to display a collection of concise information.
   <Basic />
 </Example>
 
-<Example title="Semantic KIND values" path="tag/kinds.tsx">
+<Example title="Supported KIND values" path="tag/kinds.tsx">
   <Kinds />
 </Example>
 
-You can change the color of the tag by passing a value to the `kind` prop. Here we see the set of "semantic" color options. These will reflect the `negative`, `positive`, etc values that you use in your theme.
-
-<Example title="Primitive KIND values" path="tag/primitive.tsx">
-  <Primitive />
-</Example>
-
-In addition to the "semantic" `kind` colors, you can also use "primitive" colors such as `blue` or `green`. Some of these simply alias the "semantic" colors (and therefore your theme), but there are also color-ways not contained in the "semantic" set, such as `orange`, `purple`, and `brown`.
+<Notification
+  overrides={{ Body: { style: { width: "auto", margin: "16px 0 0 0" } } }}
+  kind={NOTIFICATION_KIND.warning}
+>
+  The following tag kinds are deprecated. Please migrate to the recommended
+  primitive kinds shown in the example above:
+  <ul>
+    <li>`neutral` → use `gray`</li>
+    <li>`primary` → use `gray`</li>
+    <li>`accent` → use `blue`</li>
+    <li>`positive` → use `green`</li>
+    <li>`warning` → use `yellow`</li>
+    <li>`negative` → use `red`</li>
+    <li>`black` → use `gray` with custom styling</li>
+    <li>`brown` → no direct replacement (deprecated color)</li>
+  </ul>
+</Notification>
+
+You can change the color of the tag by passing a value to the `kind` prop. Supported kinds include `gray`, `blue`, `green`, `yellow`, `red`, `orange`, `purple`, `magenta`, `teal`, and `lime`.
 
 <Example title="Tag hierarchy Prop Type" path="tag/variants.tsx">
   <Hierarchy />