docs(border): update token descriptions#178
Conversation
Update token docs for border width to provide clearer guidance on usage and examples for LLMs.
🦋 Changeset detectedLatest commit: 715a9f7 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
✅ Deploy Preview for red-hat-design-tokens ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
bennypowers
changed the title
Updated border descriptions to clarify usage guidelines and recommendations for each border width.
adamjohnson
left a comment
adamjohnson
left a comment
There was a problem hiding this comment.
This is what it will look like with the updated token descriptions on the uxdot Tokens > Border page.
I think these descriptions are sufficient if a little verbose for where they will be displayed. That said, perhaps we must convey this amount of information to get the guidelines across.
@adamjohnson @bennypowers Yes, definitely a bit too long for ux dot, but isn't longer better to educate LLMs? I wonder if we can keep both, a shorter version that lives on ux dot and a longer version that lives in code that the LLMs can consume. |
|
Re: verbosity : we need to aim for the least verbose description possible which still contains the total necessary information For example, if it's necessary for a certain slot to contain a particular type of element in order for that host element to be accessible, we must say that. Likewise, for a token. If it is absolutely necessary that a particular token only be used for certain purposes, we must make that explicit. |
|
@bennypowers @adamjohnson Maybe worth it to establish a max character count. |
|
around 400 chars, as a general rule. We may decide later to adjust that |
Co-authored-by: Adam Johnson <adam.b.johnson1@gmail.com>
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>
|
Key changes across all descriptions:
|
|
I think this is now an exemplary PR. Visual appearance on docs pages is of secondary concern: let's write our bible first, and gussy it up after |
github-project-automation
bot
moved this from Review 🔍
to Done ☑️
in Red Hat Design System
3 participants
Update token docs for border width to provide clearer guidance on usage and examples for LLMs.