docs(border): update token descriptions (#178)

* Update token docs descriptions in border.yml

Update token docs for border width to provide clearer guidance on usage and examples for LLMs.

* docs: update border.yml

* Update token descriptions in changeset

* Revise border width descriptions in border.yml

Updated border descriptions to clarify usage guidelines and recommendations for each border width.

* docs: format descriptions

* Refine border and radius descriptions in border.yml

* Refactor descriptions for border tokens in YAML

* Refine descriptions for border width and radius tokens

* docs: Update .changeset/seven-ligers-rule.md

Co-authored-by: Adam Johnson <adam.b.johnson1@gmail.com>

* docs: reduce border token description char counts

Key changes across all descriptions:
- Removed "This token" preambles — descriptions now start with the action directly
- Limited examples to 3 elements (e.g., "Button, Call to action, Card, Field, Table" → "Button, Card, or Field")
- Replaced "It is recommended to apply this token to" → "Recommended for"
- Replaced "leveraging" with direct language
- Replaced verbose WCAG references ("as outlined by WCAG guidelines" → "per WCAG")
- Removed filler like "a modern look and feel", "a little extra"
- Fixed typo: $descrition → $description on the default token

Assisted-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Benny Powers <web@bennypowers.com>
Co-authored-by: Benny Powers - עם ישראל חי! <bennypowers@users.noreply.github.com>
Co-authored-by: Adam Johnson <adam.b.johnson1@gmail.com>

Author: 3 people

.changeset/seven-ligers-rule.md

@@ -0,0 +1,5 @@
+---
+"@rhds/tokens": patch
+---
+
+Clarify use cases for `width` and `radius` tokens like `--rh-border-width-sm` and `--rh-border-radius-sharp`.

tokens/border.yml

@@ -4,15 +4,30 @@ border:
     $extensions:
       com.redhat.ux:
         heading: Width
+
     sm:
       $value: '{length.4xs}'
-      $description: '1px border width; Example: Secondary CTA or Button'
+      $description: >-
+        Applies a 1px border width to at least 1 side of a container. This shall be the default width for all borders and
+        lines. It should be used to establish baseline thickness or visual separation with a container or thin line. It must
+        not be used for strong directional emphasis like indicating a selected state. Recommended for elements like Button,
+        Card, or Field. Applying to all 4 sides at once is optional.
+
     md:
       $value: '{length.3xs}'
-      $description: '2px border width: Example: Alert'
+      $description: >-
+        Applies a 2px border width to at least 1 side of a container. It should be used to add emphasis or visual separation
+        beyond a 1px border. Recommended for elements needing extra thickness like Alert or Progress stepper. It must be used
+        to ensure hover, focus, and active states are discernible by more than color alone per WCAG. Applying to all 4 sides
+        at once is optional.
+
     lg:
       $value: '{length.2xs}'
-      $description: '3px border width: Example: Expanded Accordion panel'
+      $description: >-
+        Applies a 3px border width to 1 side of a container. It should be used for strong directional emphasis like indicating
+        a current page, expanded, or selected state. Recommended for elements needing heavy visual weight like Accordion,
+        Navigation, or Tabs. It must also be used for the focus indicator border per WCAG. Except for the focus indicator, it
+        should not be applied to all 4 sides at once.
 
   radius:
     $extensions:
@@ -21,11 +36,20 @@ border:
 
     sharp:
       $value: 0.0px
-      $description: Border radius reset
+      $description: >-
+        This token resets the border radius of a container back to 0 or sharp. It must be applied to all 4 corners of a
+        container at once.
+
     default:
-      $description: '3px border radius; Example: Card'
       $value: '{length.2xs}'
+      $description: >-
+        Applies a 3px border radius to at least 1 corner of a container. This shall be the default for all containers needing
+        rounded corners. It should be used to soften a container's visual footprint. Recommended for elements with subtle
+        rounded corners like Button, Card, or Dialog. It must be applied to all 4 corners of a container at once.
+
     pill:
       $value: '{length.4xl}'
-      $description: 'Pill border radius; Example: Label'
-
+      $description: >-
+        Applies a 64px border radius to at least 1 corner of a container. It should be used for elements needing a circle or
+        pill-shaped background like Avatar, Badge, or Switch. It may also be used for Hybrid style branding. Applying to all
+        4 corners at once is optional. It may replace the default 3px radius when not all corners need the same value.