From aae15e044046cbb747726a03ad62b37807fbb42d Mon Sep 17 00:00:00 2001
From: Davyd Melkon <131438868+davyd-akamai@users.noreply.github.com>
Date: Mon, 8 Jul 2024 15:37:59 +0200
Subject: [PATCH] Descriptions of alias tokens (#48)

---
 tokens/alias/light.json | 77 ++++++++++++++++++++++++++---------------
 1 file changed, 49 insertions(+), 28 deletions(-)

diff --git a/tokens/alias/light.json b/tokens/alias/light.json
index 9b36003..5b0a4f6 100644
--- a/tokens/alias/light.json
+++ b/tokens/alias/light.json
@@ -4,11 +4,13 @@
       "text": {
         "base": {
           "value": "{global.color.neutrals.white}",
-          "type": "color"
+          "type": "color",
+          "description": "Use as color for text on a dark surface"
         },
         "negative": {
           "value": "{global.color.red.90}",
-          "type": "color"
+          "type": "color",
+          "description": "Use to indicate error messages"
         },
         "warning": {
           "value": "{global.color.amber.70}",
@@ -26,87 +28,102 @@
           "default": {
             "value": "{global.color.neutrals.100}",
             "type": "color",
-            "description": "Primary text color"
+            "description": "Primary color for text"
           },
           "disabled": {
             "value": "{global.color.neutrals.50}",
-            "type": "color"
+            "type": "color",
+            "description": "Use only to indicate a disabled state of a primary text color"
           }
         },
         "secondary": {
           "default": {
             "value": "{global.color.neutrals.70}",
             "type": "color",
-            "description": "Placeholder text"
+            "description": "Secondary color for text (placeholders, hints)"
           },
           "disabled": {
             "value": "{global.color.neutrals.50}",
-            "type": "color"
+            "type": "color",
+            "description": "Use only to indicate a disabled state of a secondary text color"
           }
         },
         "link": {
           "default": {
             "value": "{global.color.brand.90}",
-            "type": "color"
+            "type": "color",
+            "description": "Use only for links"
           },
           "hover": {
             "value": "{global.color.brand.70}",
-            "type": "color"
+            "type": "color",
+            "description": "Use only as a hover on links"
           },
           "disabled": {
             "value": "{global.color.neutrals.50}",
-            "type": "color"
+            "type": "color",
+            "description": "Use only to indicate a disabled state for links"
           }
         }
       },
       "icon": {
         "base": {
           "value": "{global.color.neutrals.white}",
-          "type": "color"
+          "type": "color",
+          "description": "Use as color for icons on a dark surface"
         },
         "negative": {
           "value": "{global.color.red.70}",
-          "type": "color"
+          "type": "color",
+          "description": "Use only for icons to indicate an error state"
         },
         "warning": {
           "value": "{global.color.amber.70}",
-          "type": "color"
+          "type": "color",
+          "description": "Use only for icons to indicate a warning state"
         },
         "positive": {
           "value": "{global.color.green.70}",
-          "type": "color"
+          "type": "color",
+          "description": "Use only for icons to indicate a success state"
         },
         "informative": {
           "value": "{global.color.ultramarine.70}",
-          "type": "color"
+          "type": "color",
+          "description": "Use only for icons to indicate an info state"
         },
         "primary": {
           "default": {
             "value": "{global.color.neutrals.90}",
             "type": "color",
-            "description": "Default icon color"
+            "description": "Default color for icons"
           },
           "hover": {
             "value": "{global.color.brand.70}",
-            "type": "color"
+            "type": "color",
+            "description": "Use only as a hover state for icons"
           },
           "active": {
             "value": "{global.color.brand.90}",
-            "type": "color"
+            "type": "color",
+            "description": "Use only as a selected/active state for icons"
           },
           "disabled": {
             "value": "{global.color.neutrals.50}",
-            "type": "color"
+            "type": "color",
+            "description": "Use only as a disabled state for icons"
           }
         },
         "secondary": {
           "default": {
             "value": "{global.color.neutrals.70}",
-            "type": "color"
+            "type": "color",
+            "description": "Secondary icon color (placeholder, etc)"
           },
           "disabled": {
             "value": "{global.color.neutrals.50}",
-            "type": "color"
+            "type": "color",
+            "description": "Use only as a disabled state for a secondary icon color"
           }
         }
       }
@@ -115,7 +132,7 @@
       "normal": {
         "value": "{global.color.neutrals.30}",
         "type": "color",
-        "description": "Static component border"
+        "description": "Border color for static ui elements and components"
       },
       "neutral": {
         "value": "{global.color.neutrals.100}",
@@ -123,31 +140,35 @@
       },
       "negative": {
         "value": "{global.color.red.70}",
-        "type": "color"
+        "type": "color",
+        "description": "Use only for borders to indicate an error state"
       },
       "warning": {
         "value": "{global.color.amber.70}",
-        "type": "color"
+        "type": "color",
+        "description": "Use only for borders to indicate a warning state"
       },
       "positive": {
         "value": "{global.color.green.70}",
-        "type": "color"
+        "type": "color",
+        "description": "Use only for borders to indicate a success state"
       },
       "informative": {
         "value": "{global.color.ultramarine.70}",
-        "type": "color"
+        "type": "color",
+        "description": "Use only for borders to indicate an info state"
       }
     },
     "background": {
       "normal": {
         "value": "{global.color.neutrals.white}",
         "type": "color",
-        "description": "Default component background"
+        "description": "Primary background color"
       },
       "neutral": {
         "value": "{global.color.neutrals.5}",
         "type": "color",
-        "description": "Default page background"
+        "description": "Page background color"
       },
       "base": {
         "value": "{global.color.neutrals.100}",
@@ -173,7 +194,7 @@
       "black": {
         "value": "{global.color.neutrals.black}",
         "type": "color",
-        "description": "Global header and footer background"
+        "description": "Use only for a global header and global footer background"
       },
       "negativesubtle": {
         "value": "{global.color.red.10}",