Skip to content

Commit

Permalink
docs(stat): statistic docs cleanup (#990)
Browse files Browse the repository at this point in the history 
* docs(tag): add css props and variables

* docs(tag): checkpoint

* feat(tag): adding outline variants, styling.  Adding overview and style docs pages

* docs(tag): adding guidelines docs

* docs(tag): guidelines and accessibility tab

* docs(tag): style fixes for tag docs

* feat(card): adding white color variant

* style(tag): fix lint error, styling and demo layout

* docs(stat): overview, style, guidelines, and images

* docs(stat): accessibility tab

* chore: reverting tag merge

* chore: reverting more alert and tag changes

* docs(stat): adding cssprops, accessibility templates

* docs(stat): removing image tag, spacing

* docs(stat): summary, property descriptions, docs updates and removing widths from images

* docs(stat): updating copy for overview, style, guidelines

* docs(stat): format docs

---------

Co-authored-by: Benny Powers <web@bennypowers.com>
  • Loading branch information
@brianferry @bennypowers
brianferry and bennypowers committed Jun 1, 2023
1 parent 8f543db commit f7b6cc2
Show file tree
Hide file tree
Showing 67 changed files with 403 additions and 1,002 deletions.
5 changes: 3 additions & 2 deletions docs/_data/relatedItems.yaml
View file
Expand Up @@ -67,7 +67,7 @@ rh-spinner:
- form
- search-bar
- rh-tag
rh-statistic:
rh-stat:
- rh-blockquote
- promo
rh-subnav:
Expand Down Expand Up @@ -130,4 +130,5 @@ sticky-card:
- rh-dialog
- sticky-banner
video-thumbnail:
- rh-audio-player
- rh-audio-player

4 changes: 4 additions & 0 deletions docs/scss/_utility.scss
View file
Expand Up @@ -1222,3 +1222,7 @@ playground-project > *:defined {
playground-project > *:defined:first-child {
border-block-start: var(--rh-border-width-sm, 1px) solid var(--rh-border-subtle-on-light, #C7C7C7);
}

.full-width {
width: 100%;
}
65 changes: 25 additions & 40 deletions elements/rh-stat/docs/00-overview.md
View file
@@ -1,54 +1,39 @@
A Statistic showcases a data point or quick fact in a way that visually
stands out. It consists of a number/percentage and body text in its simplest
form. It can also include an icon, title, and a call to action.
{% section %}
## Overview

{{ tagName | getElementDescription }}

{% example palette="light",
alt="A vertically aligned stack of elements; includes a small red icon, large red data text showing 80% percent, and two lines of black body text",
src="stat-sample-element.png" %}
{% endsection %}

{% section %}
## Sample component
## Sample element
<rh-stat>
<pf-icon slot="icon" set="fas" icon="tower-cell" size="lg" style="color: #ee0000"></pf-icon>
<span slot="statistic">80%</span>
of Fortune Global 500 telecom companies<sup>1</sup>
<span>of Fortune Global 500 telecommunications companies</span>
</rh-stat>
{% endsection %}

<!-- {% repoStatus %} -->
{% repoStatus %}

<hr style="margin-block:var(--rh-space-xl) var(--rh-space-5xl);">

{% section %}
## Anatomy
Each stat is composed of a number or percentage and body text. A title, icon, or
call to action are optional elements that can provide additional information.

![A stat's anatomy consists of an icon, title, number, body text, and call to
action, in that order.]({{ './stat-anatomy.svg' | url }})
{style="--inline-img-max-width:590px;margin-block-end:var(--rh-space-3xl);text-align:center;"}

<div class="multi-column--min-400-wide">
<div>

## Title
If there's supporting text for the number, the words can be added as a
title. For example, in the phrase “more than 90%,” the words "more than”
are added as a title.

</div><div>
## Demo
View a live version of this element and see how it can be customized.

## Number
This slot should include only digits, a percentage symbol, periods, or
commas.

</div><div>

## Body text
Every stat should have body text that explains the context around the
number.

</div><div>

## Additional elements
A stat can contain a relevant icon and/or call to action.

</div>
</div>
{% playground tagName=tagName %}{% endplayground %}
{% cta href="./demo/", target="_blank" %}
View the `<rh-stat>` demo in a new tab
{% endcta %}
{% endsection %}

{% section %}
## When to use
- When you need to add visual emphasis to a statistic
- When you need to pair a data point with supporting text to add more context
- When you need to display several statistics together in a group
{% endsection %}
233 changes: 86 additions & 147 deletions elements/rh-stat/docs/10-style.md
View file
@@ -1,172 +1,111 @@
## Theme
{% section %}
## Style
A statistic is a stacked combination of elements used to visualize a data point.
By default, a statistic includes data text and body text **at a minimum**.
Optional elements include an icon, title text, and a call to action for
additional emphasis or context.

<rh-context-provider color-palette="lightest"
class="centered"
style="border-radius:var(--rh-border-radius-default,3px);">
<rh-stat>
<span slot="statistic">80%</span> of Fortune Global 500 telecom
companies<sup>1</sup>
</rh-stat>
</rh-context-provider>
{% endsection %}
{% section %}

### Anatomy
{% example palette="light",
alt="Anatomy of a statistic with annotations; number 1 is pointing to an optional icon, number 2 is pointing to optional title text, number 3 is pointing to data text, number 4 is pointing to body text, and number 5 is pointing to an optional call to action",
src="../stat-anatomy.png" %}

<rh-context-provider color-palette="darkest"
class="centered"
style="border-radius:var(--rh-border-radius-default,3px);">
<rh-stat>
<span slot="statistic">80%</span> of Fortune Global 500 telecom
companies<sup>1</sup>
</rh-stat>
</rh-context-provider>
1. Optional icon
2. Optional title text
3. Data text
4. Body text
5. Optional call to action
{.example-notes}

## Color
## Sizes
There are two available sizes and the only difference is the size of some
elements.

{% example palette="light",
width=590,
class="centered",
alt="Statistic component styling - color",
src="../stat-colors.svg" %}
alt="Default size and Large size statistics both with icons and body text; text under the default size says ‘Default size’ and text under the large size says ‘Large size’",
src="../stat-sizes.png" %}

## Sizes
The default size uses 36pt for the number and 40px for an icon. A large stat
uses 48pt for the number and 64px for an icon. Both size variations use 18pt for
body text and 20pt for titles.
| Size | Element | Current Value |
| ------- | -------------- | ------------- |
| Default | Icon size | 40px |
| Default | Data text size | 36px 2.25rem |
| Large | Icon size | 64px |
| Large | Data text size | 48px 3.0rem |

{% example palette="light",
width=752,
class="centered",
alt="Examples of stat in the default and large sizes",
src="../stat-sizes.svg" %}

## Configurations/variants
An icon can be added as the first element in a statistic.

{% cta href="/get-started/icon-library/" %}Learn more about using icons{% endcta %}

<div class="example centered">
<rh-stat icon="rh-telecom-vertical">
<span slot="statistic">80%</span>
<span>of Fortune Global 500 telecom companies<sup>1</sup></span>
</rh-stat>
</div>

A call to action can be added as the last element in a statistic.

<div class="example centered">
<rh-stat>
<span slot="statistic">80%</span>
<span>of Fortune Global 500 telecom companies<sup>1</sup></span>
<rh-cta slot="cta">
<a href="#">Learn more</a>
</rh-cta>
</rh-stat>
</div>

A stat can be placed inside a card.

{% example palette="medium",
width=406,
class="centered",
alt="Example of a stat centered in a card",
src="../stat-config-in-card.svg" %}

## Alignment
All content in a stat should use the same alignment. Currently all stat content
is centered.

<div class="example centered">
<rh-stat>
<span slot="title">More than</span>
<span slot="statistic">90%</span>
<span>of Fortune 500 companies rely on Red Hat<sup>1</sup></span>
</rh-stat>
</div>
{.full-width}

{% section %}
## Accessibility

### Color contrast

A stat's colors may change based on the theme. This is done to ensure that the
color contrast meets WCAG AA standards.

#### Light theme - primary background

{% example palette="light",
width=590,
class="centered",
alt="A stat against a white background has a red title and number, black body text, and a blue CTA.",
src="../stat-accessibility-light-theme-primary-bg.svg" %}

#### Dark theme - primary background

{% example palette="darkest",
width=590,
class="centered",
alt="A stat against a black background has a white title, white number, white body text, and a light blue CTA.",
src="../stat-accessibility-dark-theme-primary-bg.svg" %}

#### Light theme - secondary background
<!-- TODO: bring `example` palettes in line with tokens -->
<div class="example" style="background: var(--rh-color-surface-light, #f0f0f0); border-radius: var(--rh-border-radius-default, 3px);">
<div class="centered">
<img alt="A stat against a white background has a red title and number, black body text, and a blue CTA."
src="{{ '../stat-accessibility-light-theme-secondary-bg.svg' | url }}"
style="--inline-img-max-width: 590px;">
</div>
</div>

#### Dark theme - secondary background
<div class="example" style="background: var(--rh-color-surface-darker, #212427); border-radius: var(--rh-border-radius-default, 3px);">
<div class="centered">
<img alt="A stat against a dark grey background has a white title and number, very light grey body text, and a light blue CTA."
src="{{ '../stat-accessibility-dark-theme-secondary-bg.svg' | url }}"
style="--inline-img-max-width: 590px;">
</div>
</div>
{% endsection %}
## Theme

{% section %}
## Responsive design
A statistic is available in both light and dark themes. The icon, title text,
and data text for light theme are red whereas elements and text for dark theme
(not including the call to action) are white to meet accessibility contrast
requirements.

### Large screens
### Light theme

A single stat will span a maximum of 6 columns.
{% example
palette="light",
alt="Light theme statistic with a red icon, red data text, and black body text",
src="../stat-theme-light.png" %}

![Example of a stat centered in a card]({{ '../stat-responsive-desktop.svg' | url }}) {style="--inline-img-max-width: 1000px;margin-block-end:var(--rh-space-3xl);"}
### Dark theme

## Small screens
{% example
palette="darkest",
alt="Dark theme statistic with a white icon and white text styles to meet accessibility contrast requirements",
src="../stat-theme-dark.png" %}

Stats in a row on large screens will stack on smaller screens. Font sizes will
adjust based on the [mobile typography]({{ '/foundations/typography/' | url }})
scale.

![Three stats stacked in a 328px container with 16px margins on either side]({{ '../stat-responsive-mobile.svg' | url }}) {style="--inline-img-max-width:360px;margin-block-end:var(--rh-space-3xl);"}
{% endsection %}
## Configuration
### Container

{% section %}
## Spacing
By default, all elements in a statistic, no matter how many, are all stacked and
vertically aligned. In some situations, it is acceptable to align elements to
the left, for example if grouped statistics are used in several rows or if
surrounding content is all left aligned.

{% example
palette="light",
alt="Statistic with a dotted vertical line through it",
src="../stat-configuration.png" %}

### Order
A statistic was designed to be read from top to bottom. If certain optional
elements are included, the order will change.

### Within the component
{% example
palette="light",
alt="Statistic with boxes around each element slot, there are also numbers next to each box arranged 1 to 4 from top to bottom",
src="../stat-configuration-order.png" %}

The Statistic component uses [spacers]({{'/foundations/spacing' | url }}) to
define space values between elements. The default and large variations use the
same spacing.
1. Icon (always ordered first if included)
2. Title text and data text (ordered first if there is no icon)
3. Body text (ordered last if there is no call to action)
4. Call to action (always ordered last if included)
{.example-notes}

{% example palette="light",
width=348,
class="centered",
alt="Stat uses 8px of space below icon, 8px of space below number, and 24px of space below body text.",
src="../stat-spacing.svg" %}
## Space
Space values are the same for both Default and Large sizes and on all
breakpoints. To see space values when statistics are used in a layout,
go to the [Guidelines](../guidelines) page.

### Within groups of stats
{% example
palette="light",
alt="Default and Large size spacing between all elements",
src="../stat-space.png" %}

Spacing between vertically stacked stats should be 48px.
| Spacer | Current value |
| ------------------------------------------------- | ------------- |
| ![8px spacer](../stat-8px-spacer.png){width=17} | 8px |
| ![24px spacer](../stat-24px-spacer.png){width=24} | 24px |

{% example palette="light",
width=360,
class="centered",
alt="Example of two stats stacked with a 48px spacer in between.",
src="../stat-vertical-spacing.svg" %}
{.full-width}

## Interaction states
The optional call to action is the only interactive element. Go to the
[Call to action](../../call-to-action) page to view the interaction
states.
{% endsection %}

0 comments on commit f7b6cc2

Please sign in to comment.