Document Trending indicator and Card stamp (#2785)

Co-authored-by: codecalm <codecalm@gmail.com>

docs/pages/ui/components/card.mdx

@@ -73,6 +73,24 @@ Add a status color to your card, either at the top or on the side of the card, t
 <div class="row row-deck"> <div class="col-md-6"> <div class="card"> <div class="card-status-top bg-danger"></div> <div class="card-body"> <h3 class="card-title">Card with top status</h3> <p class="text-secondary"> Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aperiam deleniti fugit incidunt, iste, itaque minima neque pariatur perferendis sed suscipit velit vitae voluptatem. </p> </div> </div> </div> <div class="col-md-6"> <div class="card"> <div class="card-status-start bg-green"></div> <div class="card-body"> <h3 class="card-title">Card with side status</h3> <p class="text-secondary"> Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aperiam deleniti fugit incidunt, iste, itaque minima neque pariatur perferendis sed suscipit velit vitae voluptatem. </p> </div> </div> </div> </div>
 </Example>
 
+## Card stamp
+
+Use a card stamp to put a large, faded icon in the top corner of a card. It is only a decoration, so it never covers the text and it does not react to clicks.
+
+Add a `.card-stamp` element as a direct child of the card, before the card body. Put the icon in a `.card-stamp-icon` element inside it.
+
+<Example bg="surface-secondary" column>
+<div class="card"> <div class="card-stamp"> <div class="card-stamp-icon bg-yellow"> <Icon name="bell" /> </div> </div> <div class="card-body"> <h3 class="card-title">Card with a stamp</h3> <p class="text-secondary">Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aperiam deleniti fugit incidunt, iste, itaque minima neque pariatur.</p> </div> </div>
+</Example>
+
+## Card stamp size and color
+
+Add the `card-stamp-lg` class to make the stamp bigger. Change the circle color with a `bg-*` class, and the icon color with a `text-*` class.
+
+<Example bg="surface-secondary">
+<div class="row row-deck"> <div class="col-md-6"> <div class="card"> <div class="card-stamp card-stamp-lg"> <div class="card-stamp-icon bg-primary"> <Icon name="ghost" /> </div> </div> <div class="card-body"> <h3 class="card-title">Large stamp</h3> <p class="text-secondary">The large stamp is a good fit for banners and wide cards.</p> </div> </div> </div> <div class="col-md-6"> <div class="card bg-primary text-primary-fg"> <div class="card-stamp"> <div class="card-stamp-icon bg-white text-primary"> <Icon name="star" /> </div> </div> <div class="card-body"> <h3 class="card-title">Stamp on a color card</h3> <p>Use a white circle with a colored icon on a card with a background color.</p> </div> </div> </div> </div>
+</Example>
+
 ## Stacked card
 
 Use the `card-stacked` class to stack up multiple cards, if you want to save screen space or create a visually appealing effect.

docs/pages/ui/components/trending.mdx

@@ -0,0 +1,82 @@
+---
+title: Trending
+summary: A trend indicator shows how a value changed. It joins the number with an arrow and a color, so users can read the direction at a glance.
+description: Show value change with a trend indicator.
+layout: '@layouts/DocsMdxLayout.astro'
+---
+import Example from '@components/Example.astro';
+import Icon from '@ui/Icon.astro';
+
+## Overview
+
+A trend indicator is a small inline element. It shows a number and an arrow next to it. Use it next to a metric, in a stats card, or in a table row.
+
+There is no dedicated class for it. Build it from utilities: `d-inline-flex` and `align-items-center` to keep the number and the icon in one line, `lh-1` to keep the line short, and a text color that matches the direction.
+
+<Example centered>
+<span class="text-green d-inline-flex align-items-center lh-1">25% <Icon name="arrow-up" size="sm" class="ms-0" /></span>
+</Example>
+
+## Variants
+
+### Direction
+
+Use three states to describe the change. Pick the color and the icon together, so they always tell the same story.
+
+| Change | Color | Icon |
+| --- | --- | --- |
+| Up | `text-green` | `arrow-up` |
+| No change | `text-muted` | `minus` |
+| Down | `text-red` | `arrow-down` |
+
+<Example centered>
+<span class="text-green d-inline-flex align-items-center lh-1">25% <Icon name="arrow-up" size="sm" class="ms-0" /></span> <span class="text-muted d-inline-flex align-items-center lh-1">0% <Icon name="minus" size="sm" class="ms-0" /></span> <span class="text-red d-inline-flex align-items-center lh-1">-12% <Icon name="arrow-down" size="sm" class="ms-0" /></span>
+</Example>
+
+### Unit
+
+The unit is only text after the number. Use a percent sign, a currency, or no unit at all.
+
+<Example centered>
+<span class="text-green d-inline-flex align-items-center lh-1">8% <Icon name="arrow-up" size="sm" class="ms-0" /></span> <span class="text-green d-inline-flex align-items-center lh-1">4.2K <Icon name="arrow-up" size="sm" class="ms-0" /></span> <span class="text-red d-inline-flex align-items-center lh-1">-3 <Icon name="arrow-down" size="sm" class="ms-0" /></span>
+</Example>
+
+### Size
+
+The indicator takes the font size of its parent. Put it in a heading or use a text size utility to make it bigger or smaller.
+
+<Example centered vertical>
+<span class="text-green d-inline-flex align-items-center lh-1 small">15% <Icon name="arrow-up" size="sm" class="ms-0" /></span> <span class="text-green d-inline-flex align-items-center lh-1">15% <Icon name="arrow-up" size="sm" class="ms-0" /></span> <span class="text-green d-inline-flex align-items-center lh-1 h2 m-0">15% <Icon name="arrow-up" class="ms-0" /></span>
+</Example>
+
+## Examples
+
+### Next to a value
+
+Place the indicator after the number. Use `align-items-baseline` on the wrapper, so the number and the indicator sit on the same line.
+
+<Example>
+<div> <div class="text-secondary">Today's sales</div> <div class="d-flex align-items-baseline"> <div class="h3 me-2 mb-0">6,782</div> <span class="text-green d-inline-flex align-items-center lh-1">7% <Icon name="arrow-up" size="sm" class="ms-0" /></span> </div> </div>
+</Example>
+
+### In a stats card
+
+This is the most common place for the indicator. The value stays on the left and the change on the right.
+
+<Example bg="surface-secondary" column>
+<div class="card"> <div class="card-body"> <div class="row align-items-center"> <div class="col"> <div class="text-secondary">New clients</div> <div class="h3 m-0">1,352</div> </div> <div class="col-auto"> <span class="text-red d-inline-flex align-items-center lh-1">-4% <Icon name="arrow-down" size="sm" class="ms-0" /></span> </div> </div> </div> </div>
+</Example>
+
+### In a table
+
+Use it in a table cell to compare rows quickly.
+
+<Example>
+<table class="table"> <thead> <tr> <th>Product</th> <th>Sales</th> <th>Change</th> </tr> </thead> <tbody> <tr> <td>Basic plan</td> <td>4,120</td> <td><span class="text-green d-inline-flex align-items-center lh-1">12% <Icon name="arrow-up" size="sm" class="ms-0" /></span></td> </tr> <tr> <td>Pro plan</td> <td>2,043</td> <td><span class="text-red d-inline-flex align-items-center lh-1">-7% <Icon name="arrow-down" size="sm" class="ms-0" /></span></td> </tr> <tr> <td>Team plan</td> <td>986</td> <td><span class="text-muted d-inline-flex align-items-center lh-1">0% <Icon name="minus" size="sm" class="ms-0" /></span></td> </tr> </tbody> </table>
+</Example>
+
+## Accessibility
+
+- Keep the sign in the text, for example `-12%`. Users who do not see color still get the direction.
+- The icon is hidden from screen readers, so it must not be the only carrier of meaning.
+- Add a word like `Change` in the table header or near the value, so it is clear what the number means.

shared/data/docs.json

@@ -324,6 +324,10 @@
 							"title": "Tracking",
 							"url": "/ui/components/tracking/"
 						},
+						{
+							"title": "Trending",
+							"url": "/ui/components/trending/"
+						},
 						{
 							"title": "Vector Map",
 							"url": "/ui/components/vector-map/"