Docs: Group Descriptions

[bennypowers]

Token groups which currently have lipsum for descriptions should be evaluated and the lipsum should be removed or replaced with good prose which describes how these tokens or the range of values they represent are used in the design system.

• tokens/color/accent.yml
• tokens/color/border.yml
• tokens/color/icon.yml
• tokens/color/surface.yml
• tokens/length/icon.yml
• tokens/length/length.yaml
• tokens/font/line-height.yml
• tokens/font/weight.yml
• tokens/font/size.yml
• tokens/border.yml
• tokens/opacity.yml
• tokens/shadow.yml

[bennypowers]

@coreyvickery punting to you, since we chatted about this in dms recently

[coreyvickery]

@marionnegp @markcaron I would like your feedback if these descriptions make sense or not.

Accent

Accent refers to color decoration applied to design elements within components or patterns, like Accordion, Jump links, Progress steps, Tabs, and more. Components or patterns might use an accent for navigation, but it is not mandatory to include. An accent can indicate the environment in which a component or pattern should be used. The base or default accent is blue (#0066cc) when components or patterns are used on web properties like Customer Portal as well as web or software applications. The accent changes to red (#ee0000) when components or patterns are used on redhat.com web properties.

In the Use case column, change:

• Inline link (light theme) to Base or default accent (light theme)
• Inline link (dark theme) to Base or default accent (dark theme)
• Brand red (light theme) to redhat.com web property accent (light theme)
• Brand red (dark theme) to redhat.com web property accent (dark theme)

---

Surface

Surface refers to the background color of a component or pattern specifically, like a Button or Card. This is different than the actual background of a page or layout, which refers to the last element in the z-axis. The main benefit of this distinction is being able to change one without impacting the other. You should be able to modify the background of a website or application by updating one token without modifying the background tokens of other components or patterns.

• In the --rh-color-black-700 row, change Secondary surface (dark theme) to Tertiary surface (dark theme)
• In the --rh-color-black-800 row, change Tertiary surface (dark theme) to Secondary surface (dark theme)
• In the --rh-color-black-900 row, delete or primary text (light theme)

---

Gray

Current description:

In addition to white and black, each theme features various shades of gray. Be mindful of accessibility when using text or components on top of shades of gray.

• Add this:

Do not use any of these tokens as backgrounds unless they are also included in the Surface section.

---

Box shadow

Box shadows are used to create depth and demonstrate hierarchy of layered elements.

---

Font size (headings)

• Remove text.

---

Font size (text)

• Remove text.

---

Font size (code)

• Remove text.

---

Font weight (headings)

• Change heading text from Font weights to Font weight
• Remove text.

---

Font weight (body)

• Change heading text from Font weights to Font weight
• Remove text.

---

Font weight (code)

• Change heading text from Font weights to Font weight
• Remove text.

---

Line height

• Remove text.

---

Border

Use the following tokens to customize rounded corners or border thickness.

Radius

Border radius is used to give an element rounded corners.

Width

Border width is used to control border thickness.

Color

• Remove text.

---

Opacity

Opacity specifies how transparent an element is.

---

Length

Length represents a distance value and can be relative or absolute. Relative lengths represent a measurement in terms of some other distance. Depending on the unit, this distance can be the size of a specific character, the line height, or the size of the viewport.

---

Size

Size is used to set element sizes, like icon boxes. They can also be used for width and height properties.

[marionnegp]

@coreyvickery, the Icons heading will have to be changed to Size.

Also, this might be a dumb question, but if the length tokens are using pixels, can they still represent relative lengths?