Skip to content

Commit

Permalink
docs(skeleton): some cleanup and tone of voice
Browse files Browse the repository at this point in the history
  • Loading branch information
@ianmcburnie
ianmcburnie committed Jan 4, 2024
1 parent 75d849d commit 61b459a
Showing 1 changed file with 74 additions and 105 deletions.
179 changes: 74 additions & 105 deletions docs/_includes/skeleton.html
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
<div id="skeleton">
<!-- {% include section-header.html name="skeleton" version=page.versions.skeleton %} -->
<h2>@ebay/skin/skeleton <sup class="beta">BETA</sup></h2>
<p>A skeleton provides a simplified, graphical placeholder for content that is not yet available for the client to render; they can be considered as an alternative to the <a href="#progress-spinner">progress spinner</a> in many situations.</p>
<p>A skeleton is appropriate as a placeholder for content in cases where a service or action may be slow to resolve (after 500ms or so).</p>
<p>A skeleton is not appropriate as a placeholder for content if that content has unknown dimensions which will cause unexpected page layout shift.</p>

<section class="section-notice section-notice--attention" role="region" aria-label="Attention"
aria-roledescription="Notice">
<div class="section-notice__header" id="section-notice-attention">
Expand All @@ -9,22 +13,23 @@ <h2>@ebay/skin/skeleton <sup class="beta">BETA</sup></h2>
</svg>
</div>
<div class="section-notice__main">
<h3 class="section-notice__title">Attention</h3>
<p>Skeletons are currently work in progress and in BETA mode. For guidance and appropriate usage, please reachout
the core team.</p>
<h3 class="section-notice__title">Cumulative Layout Shift (CLS)</h3>
<p>It is the developer's responsibility to ensure the <a href="https://web.dev/articles/cls">CLS metric</a> of a page is not negatively impacted by the introduction of a skeleton placeholder; <strong>a poor CLS score will occur whenever content shifts unexpectedly</strong>. Unexpected movement of page content usually happens because resources are loaded asynchronously or DOM elements get dynamically added to the page above existing content. It can also be compounded when a skeleton has dimensions that do not match the content that it is acting as a placeholder for.</p>
</div>
</section>
<p>The Skeletons are simplified versions of layouts to indicate that information has not
been fully loaded to improve the perceived performance.</p>

<p>The <a href="{{ site.url }}/skeleton-examples/">skeleton examples page</a> illustrates various techniques for implementing skeletons across some common loading scenarios.</p>

<h3 id="skeleton-types">Skeleton Types</h3>
<table class="skeleton-table-colors">
<thead>
<tr>
<th>Skeleton type</th>
<th>default</th>
<th>elevated</th>
<th>purple</th>
<th>green</th>
<th>blue</th>
<th>Skeleton</th>
<th>Default</th>
<!--<th>Elevated</th>-->
<th>Purple</th>
<th>Green</th>
<th>Blue</th>
</tr>
</thead>
<tbody>
Expand All @@ -35,11 +40,13 @@ <h3 class="section-notice__title">Attention</h3>
<div class="skeleton__avatar"></div>
</div>
</td>
<!--
<td>
<div class="skeleton skeleton--elevated" role="img" aria-label="loading">
<div class="skeleton__avatar"></div>
</div>
</td>
-->
<td>
<div class="skeleton skeleton--purple" role="img" aria-label="loading">
<div class="skeleton__avatar"></div>
Expand All @@ -63,11 +70,13 @@ <h3 class="section-notice__title">Attention</h3>
<div class="skeleton__button"></div>
</div>
</td>
<!--
<td>
<div class="skeleton skeleton--elevated" role="img" aria-label="loading">
<div class="skeleton__button"></div>
</div>
</td>
-->
<td>
<div class="skeleton skeleton--purple" role="img" aria-label="loading">
<div class="skeleton__button"></div>
Expand All @@ -91,11 +100,13 @@ <h3 class="section-notice__title">Attention</h3>
<div class="skeleton__textbox"></div>
</div>
</td>
<!--
<td>
<div class="skeleton skeleton--elevated" role="img" aria-label="loading">
<div class="skeleton__textbox"></div>
</div>
</td>
-->
<td>
<div class="skeleton skeleton--purple" role="img" aria-label="loading">
<div class="skeleton__textbox"></div>
Expand All @@ -119,11 +130,13 @@ <h3 class="section-notice__title">Attention</h3>
<div class="skeleton__image" style="height: 50px; width: 50px;"></div>
</div>
</td>
<!--
<td>
<div class="skeleton skeleton--elevated" role="img" aria-label="loading">
<div class="skeleton__image" style="height: 50px; width: 50px;"></div>
</div>
</td>
-->
<td>
<div class="skeleton skeleton--purple" role="img" aria-label="loading">
<div class="skeleton__image" style="height: 50px; width: 50px;"></div>
Expand All @@ -147,11 +160,13 @@ <h3 class="section-notice__title">Attention</h3>
<div class="skeleton__text"></div>
</div>
</td>
<!--
<td>
<div class="skeleton skeleton--elevated" role="img" aria-label="loading">
<div class="skeleton__text"></div>
</div>
</td>
-->
<td>
<div class="skeleton skeleton--purple" role="img" aria-label="loading">
<div class="skeleton__text"></div>
Expand All @@ -171,72 +186,11 @@ <h3 class="section-notice__title">Attention</h3>
</tbody>
</table>

<h3 id="skeleton-usage">Usage</h3>
<ul>
<li>Skeletons should only appear once loading time reaches 500ms or longer.</li>
<li>Not every page or page section requires skeleton.</li>
<li>Skeletons are primarily intended as a replacement for
spinners.</li>
<li><b>Do not</b> use skeletons if either layout/dimensions are not known.</li>
<li><b>Do not</b> use skeletons if it will cause layout to shift content.</li>
<li><b>Do not</b> use skeletons for content that is below the fold i.e, for lazy loading images etc.</li>
</ul>

<h4>Labelling</h4>
<p>By default, the skeleton loaders doesn't convey to screen reader users in a meaningful way. The <span
class="highlight">aria-label</span>
attribute, set to "loading", is utilized to signify the loading state of the
skeleton loader to screen reader users. To prevent the screen reader from repeating the label, the
<span class="highlight">aria-label</span> attribute should be positioned on the container element. For a better
understanding of this subtlety, please refer to below examples.
</p>
<h4>Colors</h4>
<p>On larger screens, skeleton loaders use standard fill color in the background where as a shimmer is applied on
smaller screens. An elevated color can be applied by overriding container skeletons with their color classes respectively. For
example, any skeleton shape can inherit elevated background using <span class="highlight">skeleton--elevated</span>
class.</p>
<p>Similarly, for AI purposes, respective colors can be applied using <span
class="highlight">skeleton--purple</span>, <span class="highlight">skeleton--green</span> and <span
class="highlight">skeleton--blue</span> classes. For example, checkout the examples under <a href="#skeleton-custom">custom skeletons</a> section.</p>
<p>On large screens, skeleton loaders use a solid fill for background color; on small screens, a shimmer is applied.</p>
<p>The color can be changed to purple, green or blue by applying the appropriate modifier, e.g. <span class="highlight">skeleton--green</span>. View the <a href="#skeleton-composite">composite skeletons</a> examples for further details.</p>

<h3>Skeleton Examples</h3>
<p>The <a href="{{ site.url }}/skeleton-examples/">Skeleton examples</a> shown illustrate when to utilize skeletons
and various techniques for implementing them in different loading scenarios.</p>

<h3 id="skeleton-vars">CSS Properties</h3>
<p>We've set up <span class="highlight">CSS</span> properties to provide developers with easy reference for responsive
adjustments of UIs. The <span class="highlight">CSS</span> properties allow for customization of skeletons for UIs
that require it, but <strong>please use them sparingly and be mindful of the impact those overrides can
have</strong>.</p>

<section class="section-notice section-notice--information" role="region" aria-label="Information"
aria-roledescription="Notice">
<div class="section-notice__header" id="section-notice-information">
<svg class="icon icon--information-filled-16" focusable="false" height="16" width="16" aria-label="Information">
{% include symbol.html name="information-filled-16" %}
</svg>
</div>
<div class="section-notice__main">
<h3 class="section-notice__title">The <span class="highlight">CSS</span> properties to allow for customization
</h3>
<p>These properties allow for customization of skeletons for UIs that require it, but please <em>use them
sparingly and be mindful of the impact those overrides can have</em>.</p>
</div>
</section>

{% highlight css %}
/* TBD: Need to add more component level skeleton overrides for further customizations */
--btn-border-radius: 20px; /* To set border radius of the regular skeleton button */
--text-border-radius: 3px; /* To set border radius of the skeleton text */
--avatar-border-radius: 50%; /* To set border radius of the skeleton avatar */
--image-border-radius: 8px; /* To set border radius of the skeleton image */
--textbox-border-radius: 3px; /* To set border radius of the skeleton textbox */
--skeleton-background: var(--color-loading-fill); /* The default background color of the skeleton */
{% endhighlight %}

<h3>Building blocks</h3>
<h4 id="skeleton-avatar">Avatar</h4>
<p>Use the <span class="highlight">skeleton__avatar</span> class to load a skeleton avatar.</p>
<h3 id="skeleton-avatar">Avatar Skeleton</h3>
<p>Use the <span class="highlight">skeleton__avatar</span> class to create a skeleton placeholder for an avatar.</p>
<div class="demo">
<div class="demo__inner">
<div class="skeleton" role="img" aria-label="loading">
Expand All @@ -250,10 +204,9 @@ <h4 id="skeleton-avatar">Avatar</h4>
</div>
{% endhighlight %}

<h4 id="skeleton-button">Button</h4>
<h5>Regular Button</h5>
<p>Use the <span class="highlight">skeleton__button</span> class, to create a minimal, default skeleton button loader.
</p>
<h3 id="skeleton-button">Button Skeleton</h3>

<p>Use the <span class="highlight">skeleton__button</span> class to create a skeleton placeholder for the default button shape.</p>
<div class="demo">
<div class="demo__inner">
<div class="skeleton" role="img" aria-label="loading" style="width: 200px;">
Expand All @@ -266,8 +219,8 @@ <h5>Regular Button</h5>
<div class="skeleton__button"></div>
</div>
{% endhighlight %}
<h5>Small Button</h5>
<p>Use the <span class="highlight">small</span> modifier to decrease the size of the skeleton.</p>

<p>Use the <span class="highlight">small</span> modifier to match the shape of a small button.</p>
<div class="demo">
<div class="demo__inner">
<div class="skeleton" role="img" aria-label="loading" style="width: 200px;">
Expand All @@ -280,8 +233,8 @@ <h5>Small Button</h5>
<div class="skeleton__button skeleton__button--small"></div>
</div>
{% endhighlight %}
<h5>Large Button</h5>
<p>Use the <span class="highlight">large</span> modifier to increase the size of the skeleton.</p>

<p>Use the <span class="highlight">large</span> modifier to match the shape of a large button.</p>
<div class="demo">
<div class="demo__inner">
<div class="skeleton" role="img" aria-label="loading" style="width: 200px;">
Expand All @@ -295,8 +248,8 @@ <h5>Large Button</h5>
</div>
{% endhighlight %}

<h4 id="skeleton-textbox">Textbox</h4>
<p>Use the <span class="highlight">skeleton__textbox</span> class, when loading form controls. </p>
<h3 id="skeleton-textbox">Textbox Skeleton</h3>
<p>Use the <span class="highlight">skeleton__textbox</span> class to create a skeleton placeholder for a textbox.</p>
<div class="demo">
<div class="demo__inner">
<div class="skeleton" role="img" aria-label="loading" style="width: 200px;">
Expand All @@ -310,27 +263,39 @@ <h4 id="skeleton-textbox">Textbox</h4>
</div>
{% endhighlight %}

<h4 id="skeleton-image">Image</h4>
<p>Use the <span class="highlight">skeleton__image</span> class, while loading images. By default, skeleton image
loader inherits the height and width of the element.</p>
<h3 id="skeleton-image">Image Skeleton</h3>
<p>Use the <span class="highlight">skeleton__image</span> class to create a skeleton placeholder for an image.</p>

<div class="demo">
<div class="demo__inner">
<div class="skeleton" role="img" aria-label="loading">
<div class="skeleton__image" style="height: 50px; width: 50px;"></div>
<div class="skeleton__image" style="height: 200px; width: 200px;"></div>
</div>
</div>
</div>
{% highlight html %}
<div class="skeleton" role="img" aria-label="loading">
<div class="skeleton__image" style="height: 50px; width: 50px;"></div>
</div>
{% endhighlight %}

<p>Notice that the height and width must be set on the <span class="highlight">skeleton__image</span> element.</p>

<div class="demo">
<div class="demo__inner">
<div class="skeleton" role="img" aria-label="loading">
<div class="skeleton__image" style="height: 200px; width: 200px;"></div>
</div>
</div>
</div>
{% highlight html %}
<div class="skeleton" role="img" aria-label="loading">
<div class="skeleton__image" style="height: 200px; width: 200px;"></div>
</div>
{% endhighlight %}

<h4 id="skeleton-text">Text</h4>
<p>Use the <span class="highlight">skeleton__text</span> class, to display content block in a single
row.</p>
<h3 id="skeleton-text">Text Block Skeleton</h3>
<p>Use the <span class="highlight">skeleton__text</span> class to create a skeleton for a single block of text.</p>
<div class="demo">
<div class="demo__inner">
<div class="skeleton" role="img" aria-label="loading" style="width: 200px;">
Expand All @@ -343,9 +308,8 @@ <h4 id="skeleton-text">Text</h4>
<div class="skeleton__text skeleton__text--small"></div>
</div>
{% endhighlight %}
<h5>Variant: Large Text</h5>
<p>Use the <span class="highlight">skeleton__text--large</span> class, to display large content block in a single
row.</p>

<p>Use the <span class="highlight">skeleton__text--large</span> modifier to match the shape of a large block of text.</p>
<div class="demo">
<div class="demo__inner">
<div class="skeleton" role="img" aria-label="loading" style="width: 200px;">
Expand All @@ -359,9 +323,7 @@ <h5>Variant: Large Text</h5>
</div>
{% endhighlight %}

<h5>Variant: Two row text</h5>
<p>Use the <span class="highlight">skeleton__text--multiline</span> classes, to display content changes in
multiple rows.</p>
<p>Use the <span class="highlight">skeleton__text--multiline</span> mofifier to create a skeleton for two lines of text.</p>
<div class="demo">
<div class="demo__inner">
<div class="skeleton" role="img" aria-label="loading" style="width: 200px;">
Expand All @@ -375,9 +337,9 @@ <h5>Variant: Two row text</h5>
</div>
{% endhighlight %}

<h4 id="skeleton-custom">Custom Skeletons</h4>
<h5>Tile</h5>
<p>A custom tile layout is shown here with image and text content.</p>
<h3 id="skeleton-composite">Composite Skeleton</h3>
<p>Combinations of skeletons can form a custom placeholder for more complex content, such as a typical eCommerce item tile in the example below.</p>

<div class="demo">
<div class="demo__inner">
<div class="skeleton skeleton--purple" role="img" aria-label="loading" style="width: 225px;">
Expand All @@ -393,8 +355,7 @@ <h5>Tile</h5>
</div>
{% endhighlight %}

<h5>Inline blocks</h5>
<p>To use skeletons inline, replace div with span.</p>
<p>Here is a skeleton for a compact user profile. Notice that a <span class="highlight">div</span> tag can be replaced with a <span class="highlight">span</span> tag for inline-block layout of elements.</p>
<div class="demo">
<div class="demo__inner">
<div class="skeleton skeleton--blue" role="img" aria-label="loading">
Expand All @@ -408,4 +369,12 @@ <h5>Inline blocks</h5>
<span class="skeleton__avatar"></span>
<span class="skeleton__text skeleton__text--multiline" style="width: 200px; vertical-align: top;"></span>
</div>
{% endhighlight %}
{% endhighlight %}

<h3 id="skeleton-variables">Skeleton Variables <sup>EXPERIMENTAL</sup></h3>
<p>The following custom properties (aka CSS Variables) are available for component-level overrides and other general theming purposes.</p>

<ul>
<li>--skeleton-background</li>
</ul>
</div>

0 comments on commit 61b459a

Please sign in to comment.