@beehexa/design-rules 0.0.0-stage → 2611.3.2

package/dist/docs/src/content/foundations/styles/color/tokens.mdx

@@ -0,0 +1,55 @@
+---
+title: Tokens
+description: How colour token names are built, every role token with its light and dark value, how to use them in code, and how to ask for a new one.
+order: 4
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+**Every colour token name says what is painted, what it means, how strong it is and what is happening.**
+
+## How names are built
+
+`color.{property}.{role}.{emphasis}.{state}`. A part is left out when it is the default.
+
+<ColorDemo kind="anatomy" />
+
+| Part | Values |
+|---|---|
+| Property | `text`, `icon`, `link`, `surface`, `background`, `border`, `skeleton` |
+| Role | `neutral` (left out), `brand`, `danger`, `warning`, `success`, `info`, `inverse`, `disabled`; surfaces: `page`, `subtle`, `inverse`, `scrim` |
+| Emphasis | Text: default, `subtle`, `subtlest`. Fills: `subtle`, default, `bold`. Borders: default, `bold` |
+| State | `hover`, `pressed`, `selected`, `focus` |
+
+`color.background.danger.bold.hover` is the solid danger fill on hover. Two names name the fill under the text instead of a role: `text.on-bold` (on any solid status fill) and `text.on-brand` (on the brand yellow).
+
+In CSS, write `--bh-` and the name with dots as hyphens: `color.text.subtle` is `var(--bh-color-text-subtle)`.
+
+Use role tokens. The [palette](/foundations/styles/color/palette/) feeds them and is never used directly (see [How colour works](/foundations/styles/color/#how-colour-works)).
+
+## Text and icons
+
+<ColorDemo kind="roles" group="text" />
+
+<ColorDemo kind="roles" group="icon" />
+
+## Surfaces
+
+<ColorDemo kind="roles" group="surface" />
+
+## Backgrounds
+
+<ColorDemo kind="roles" group="background" />
+
+## Borders
+
+<ColorDemo kind="roles" group="border" />
+
+## Missing a token
+
+1. Check [Find the token](/foundations/styles/color/usage/#find-the-token) and the list below.
+2. Ask the design system team. Say where you need it, and propose a name from the four parts that points at a step with the right job (fill at 3, border at 7, text at 11).
+3. The team checks its contrast in both themes and adds it. Use it only after it is released.
+
+## All colour tokens
+
+<ColorDemo kind="tokens" />

package/dist/docs/src/content/foundations/styles/color/usage.mdx

@@ -0,0 +1,111 @@
+---
+title: Usage
+description: Which token to use for each part of a screen, how status, emphasis and states are coloured, and what not to do.
+order: 2
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+**Pick a token by what you are painting and what it means, not by how it looks.**
+
+<ColorDemo kind="example" />
+
+## Find the token
+
+| I need | Use |
+|---|---|
+| Page background | `surface.page` |
+| Card, panel, dialog | `surface`, edge `border` |
+| Sidebar, table header, quiet area | `surface.subtle` |
+| Body text, headings, labels | `text` |
+| Descriptions, secondary table columns, navigation | `text.subtle` |
+| Metadata, timestamps, helper text, breadcrumbs | `text.subtlest` |
+| Placeholder | `text.subtlest` |
+| Link | `link`; on hover `link.hover` |
+| Icon next to text | `icon`; less important `icon.subtle` |
+| Divider, card edge | `border` |
+| Edge of an input, checkbox or select | `border.bold` |
+| Keyboard focus ring | `border.focus`, 2 px, 2 px away |
+| Primary button | `background.neutral.bold`, `text.inverse` |
+| Default button | `surface`, `border`, `text`; on hover `background.neutral.subtle.hover` |
+| Destructive button | `background.danger.bold`, `text.on-bold` |
+| Row or menu item on hover | `background.neutral.subtle.hover` |
+| Selected row, tab or menu item | `background.selected` and a second cue |
+| Current page in the navigation | `border.selected` bar, `background.selected`, `aria-current="page"` |
+| Error under a field | `text.danger`, `icon.danger` |
+| Banner for a status | `background.{role}.subtle`, `border.{role}.subtle`, `text`, `icon.{role}` |
+| Status in a table row | A [label](#labels) |
+| Tooltip, toast | `surface.inverse`, `text.inverse` |
+| Layer behind a dialog or drawer | `surface.scrim` |
+| Loading placeholder | `skeleton`, sheen `skeleton.subtle` |
+| Code block | `code.background`, `code.text` |
+| Brand note | `background.brand.subtle`, `border.brand.subtle` |
+| Disabled control | `background.disabled`, `text.disabled`, `border.disabled` |
+
+Not in the table? Build the name from its four parts (see [Tokens](/foundations/styles/color/tokens/)). If no token exists, ask for one; don't pick the nearest colour.
+
+## Surfaces and backgrounds
+
+**Surfaces are the layers of a screen; backgrounds fill the things on them.**
+
+<ColorDemo kind="surfaces" />
+
+`surface.scrim` goes behind dialogs and drawers only, one layer, at its own opacity.
+
+## Emphasis
+
+<ColorDemo kind="emphasis" />
+
+## Status
+
+**Every status is one of five roles. Pick by what the person needs to do, and always say it in words.**
+
+### Choosing a status
+
+| Role | Use when | HexaSync examples |
+|---|---|---|
+| Info | Something is happening or worth knowing; no action needed. | Syncing, queued, importing |
+| Success | It worked. | Synced, connected, completed |
+| Warning | It works now but needs attention soon. | Partial sync, token expires in 3 days, rate limited |
+| Danger | It failed or is blocked, or the action destroys something. | Failed, disconnected, delete |
+| Neutral | Nothing is happening and nothing is wrong. | Paused, draft, skipped, archived |
+
+Warning is orange, not yellow: yellow is the brand. There is no sixth level; say the difference in words ("Failed 3 times").
+
+### Status colours
+
+<ColorDemo kind="status" />
+
+<ColorDemo kind="banners" />
+
+<ColorDemo kind="dodont" item="warning" />
+
+### Labels
+
+<ColorDemo kind="labels" />
+
+| | Label | State label |
+|---|---|---|
+| Looks | Outline in the role's `border`, text in its `text` | Fill in the role's `bold`, text and icon in `text.on-bold` |
+| Size | 20 px, padding 6 px; large 24 px, 8 px | 32 px, padding 12 px |
+| Use | Many per screen: table rows, tags | One per page: the status the page is about |
+
+## Interaction states
+
+**Add `.hover` or `.pressed` to the token at rest; never use opacity or an overlay.**
+
+<ColorDemo kind="states" />
+
+| State | Use |
+|---|---|
+| Hover, pressed | The rest token plus `.hover` or `.pressed` |
+| Selected | `background.selected` and a second cue |
+| Focus | 2 px `border.focus` ring, 2 px away |
+| Disabled | `background.disabled`, `text.disabled`, `border.disabled` |
+
+On a row or menu item each state sits one step further from the background: hover, then selected, then selected on hover. A hovered row is always lighter than a selected one, so it never looks selected.
+
+More on [Interaction states](/foundations/styles/interaction-states/).
+
+## Buttons
+
+<ColorDemo kind="actions" />

package/dist/docs/src/content/foundations/styles/data-visualization.mdx

@@ -0,0 +1,11 @@
+---
+title: "Data visualization"
+description: "Colours, type and rules for charts, KPI tiles and other data displays."
+order: 13
+planned:
+  - "A chart palette for series, with contrast in light and dark"
+  - "Status colours in charts"
+  - "Chart types and when to use each"
+  - "Axis, legend, tooltip and number formats"
+  - "Accessible charts: not by colour alone, text alternatives"
+---

package/dist/docs/src/content/foundations/styles/elevation.mdx

@@ -0,0 +1,12 @@
+---
+title: Elevation
+description: Shadows that show which surfaces sit above others.
+order: 8
+---
+import TokenTable from '../../../components/TokenTable.astro';
+
+- `elevation.shadow.raised`: cards that sit on the page.
+- `elevation.shadow.overlay`: dropdowns, popovers and dialogs that float above content.
+
+## Tokens
+<TokenTable prefix="elevation" />

package/dist/docs/src/content/foundations/styles/icons/accessibility.mdx

@@ -0,0 +1,72 @@
+---
+title: Accessibility
+description: How icons get a name or stay silent, why icon-only buttons need a tooltip, and the contrast and target size icons must meet.
+order: 3
+---
+import IconDemo from '../../../../components/IconDemo.astro';
+
+**An icon is either decorative and hidden, or it has a name. A clickable icon is always inside a button or a link of at least 24 × 24.**
+
+| Check | Rule | WCAG 2.2 |
+|---|---|---|
+| Decorative icon | Hidden with `aria-hidden="true"` | 1.1.1 |
+| Icon-only button or link | Has a name (`aria-label`) and a matching tooltip | 1.1.1, 2.5.3, 4.1.2 |
+| Icon that carries meaning | 3:1 contrast or more with its background | 1.4.11 |
+| Status | Written in words, never icon or colour alone | 1.4.1 |
+| Target | 24 × 24 or more; 32 × 32 icon buttons in products | 2.5.8 |
+
+## Decorative icons
+
+**When text sits next to the icon, the icon is decorative.** Hide it, so screen readers read the label once.
+
+Lucide does this for you: an icon with no `aria-label`, `aria-labelledby`, `role` or `title` gets `aria-hidden="true"`. Don’t add a label to an icon that already has text next to it.
+
+<IconDemo kind="dodont" item="decorative" />
+
+## Icon-only buttons
+
+**Name the button, not the icon.** Put the name on the `<button>` or `<a>` with `aria-label`. The icon inside stays hidden.
+
+- The name says what happens: “Delete store”, not “Trash” or “Icon”.
+- Add a tooltip with the same words, on hover and on keyboard focus. The tooltip must start with the button’s name, so speech input users can say what they see (WCAG 2.5.3).
+- Use an icon-only button only for well-known actions. See [Icon and label](/foundations/styles/icons/usage/#icon-and-label).
+
+```html
+<button type="button" aria-label="Settings">
+  <svg aria-hidden="true">…</svg>
+</button>
+```
+
+<IconDemo kind="dodont" item="tooltip" />
+
+## Meaningful icons on their own
+
+When an icon is the only sign of something, such as a status icon in a narrow table column, give the icon itself a name: `role="img"` and `aria-label="Failed"`. Prefer writing the status in words.
+
+## Contrast
+
+**Icons that carry meaning need 3:1 against their background** (WCAG 1.4.11). Every `color.icon.*` token meets 3:1 on the backgrounds it is paired with, in light and dark; the build checks it. Decorative icons and icons in disabled controls have no minimum.
+
+See every pair in [Color › Accessibility](/foundations/styles/color/accessibility/).
+
+## Target size
+
+**Anything you can click is at least 24 × 24** (WCAG 2.5.8). In Beehexa products, icon buttons are 32 × 32 with a 16 px icon. The icon is never the only thing to click.
+
+<IconDemo kind="target" />
+
+<IconDemo kind="dodont" item="target" />
+
+## Keyboard and focus
+
+- The button or link gets focus, never the icon. Don’t add `tabindex` to an `<svg>`.
+- The focus ring goes around the whole 32 × 32 button.
+- A tooltip opens on focus as well as hover, and closes with Escape.
+
+## Checklist
+
+- Every icon next to text is hidden from screen readers.
+- Every icon-only button has a name and a tooltip with the same words.
+- No status is shown by an icon or colour alone.
+- Meaningful icons reach 3:1; the token already does if you use the right one.
+- Every clickable icon sits in a target of 24 × 24 or more.

package/dist/docs/src/content/foundations/styles/icons/code.mdx

@@ -0,0 +1,171 @@
+---
+title: Code
+description: How Vue products install, import, size, colour and label Lucide icons, with short notes for React and Astro.
+order: 4
+---
+
+**Products use Lucide directly. Install the Lucide package for your framework, pin the version and import each icon by name.**
+
+## Packages
+
+| Framework | Package | Version |
+|---|---|---|
+| Vue, for Beehexa products | `@lucide/vue` | 1.62.0 |
+| React | `lucide-react` | 1.62.0 |
+
+Every product uses the same Lucide version as this site, so the icons match the [Library](/foundations/styles/icons/library/). The icons are bundled into the app at build time. There is no request to a CDN.
+
+## Install
+
+```bash
+npm install @lucide/vue@1.62.0 --save-exact
+```
+
+Pin the exact version, with no `^` or `~`. A new Lucide version can change a shape or rename an icon, so raise the version on purpose. See [Updating Lucide](#updating-lucide).
+
+## Import
+
+Import each icon by name. Names are the Library names in PascalCase: `refresh-cw` becomes `RefreshCw`. Only the icons you import end up in the bundle.
+
+```vue
+<script setup lang="ts">
+import { RefreshCw } from '@lucide/vue';
+</script>
+
+<template>
+  <button type="button" class="bh-button">
+    <RefreshCw :size="16" />
+    Sync now
+  </button>
+</template>
+```
+
+Don’t import the whole set with `import * as`. It puts every icon in the bundle.
+
+## Default size
+
+Lucide draws icons at 24 px. Beehexa products use 16 px by default. Set it once in the root component:
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { setLucideProps } from '@lucide/vue';
+
+setLucideProps({ size: 16 });
+</script>
+```
+
+Then set `size` only for a 20, 24 or 32 px icon.
+
+## Props
+
+| Prop | Lucide default | Beehexa rule |
+|---|---|---|
+| `size` | 24 | 16 by default. 20, 24 or 32 only where Usage says so. Nothing else. |
+| `color` | `currentColor` | Leave it. Set the colour on the parent with an icon colour token. |
+| `stroke-width` | 2 | Don’t change it. |
+| `non-scaling-stroke` | `false` | Don’t turn it on. Don’t use its older name, absolute-stroke-width, either. |
+| `aria-label` | none | Only for a meaningful icon on its own, together with the img role. |
+
+## Size
+
+Use the `size` prop, or set the size in CSS on the `svg`. Both keep the stroke in scale.
+
+```vue
+<RefreshCw :size="20" />
+```
+
+## Colour
+
+```css
+.sync-status {
+  color: var(--bh-color-icon-success);
+}
+```
+
+```vue
+<span class="sync-status"><CircleCheck /> Synced</span>
+```
+
+## Spacing
+
+Set the gap on the control, from its size: 4 px (`space.050`) with a 16 px icon in small and default controls, 8 px (`space.100`) with a 20 or 24 px icon. See [Usage › Spacing](/foundations/styles/icons/usage/#spacing).
+
+```css
+.bh-button {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--bh-space-050);
+}
+.bh-button.is-large {
+  gap: var(--bh-space-100);
+}
+```
+
+## Accessibility
+
+Lucide hides an icon from screen readers with `aria-hidden="true"`, unless you give it an `aria-*`, `role` or `title` prop. Name icon-only buttons on the button, and add a tooltip with the same text.
+
+```vue
+<a-tooltip title="Settings">
+  <button type="button" class="icon-button" aria-label="Settings">
+    <Settings />
+  </button>
+</a-tooltip>
+```
+
+A meaningful icon on its own gets a role and a label, which also removes `aria-hidden`:
+
+```vue
+<CircleX role="img" aria-label="Failed" />
+```
+
+## Inside Ant Design Vue
+
+Put the icon in the `icon` slot and add the `anticon` class, so Ant Design Vue lines it up like its own icons.
+
+```vue
+<a-button>
+  <template #icon><Plus class="anticon" /></template>
+  Add store
+</a-button>
+```
+
+## React
+
+`lucide-react` has the same icons and props, in camelCase. Set the default size once with `LucideProvider`.
+
+```tsx
+import { LucideProvider, RefreshCw } from 'lucide-react';
+
+<LucideProvider size={16}>
+  <button type="button">
+    <RefreshCw />
+    Sync now
+  </button>
+</LucideProvider>
+```
+
+## Astro
+
+beehexa.design uses `@lucide/astro`. Import each icon from its own file, so the build stays fast:
+
+```astro
+---
+import Search from '@lucide/astro/icons/search';
+---
+<button class="icon-button" type="button" aria-label="Search">
+  <Search size={20} />
+</button>
+```
+
+
+## Custom icons
+
+Lucide covers what Beehexa needs today. If an icon is ever missing, draw it on Lucide’s 24 px grid with the same stroke and caps, name it in kebab-case with a `bh-` prefix, and add it to the library.
+
+## Updating Lucide
+
+1. Read the Lucide release notes for renamed or changed icons.
+2. Check that every icon in [Common actions](/foundations/styles/icons/usage/#common-actions) still exists.
+3. Raise the pinned version in the product, and ask the design system team to update the Library, so it shows the same icons.

package/dist/docs/src/content/foundations/styles/icons/index.mdx

@@ -0,0 +1,62 @@
+---
+title: Icons
+description: Beehexa products use Lucide, an open-source set of outline icons, directly. A few rules cover size, colour, spacing, labels and accessibility.
+order: 11
+sidebarLabel: Overview
+---
+import IconDemo from '../../../../components/IconDemo.astro';
+
+Icons help people scan a screen and recognise an action. In Beehexa products they never replace words: a status is written, and most actions have a label.
+
+Beehexa uses **[Lucide](https://lucide.dev)**: about 1,900 outline icons on a 24 × 24 grid, under the ISC licence. Products import Lucide directly. There is no Beehexa icon package. We add usage rules on top.
+
+<IconDemo kind="sizes" />
+
+## Principles
+
+### Words first
+
+An icon supports a label. Use an icon on its own only for an action everyone knows, such as close, search or more, and give it a name and a tooltip.
+
+### One icon, one meaning
+
+The same idea always has the same icon, in every product. Sync is `refresh-cw` everywhere. See the [common actions](/foundations/styles/icons/usage/#common-actions).
+
+### Outline only
+
+Lucide has no filled icons. Show a selected item with the selected background and an indicator bar, not with a different icon.
+
+### Colour follows the text
+
+An icon takes the colour of the text next to it. Use a status colour only when the icon shows that status.
+
+## The rules at a glance
+
+| Rule | Value |
+|---|---|
+| Icon set | Lucide, outline only |
+| Sizes | 16 (default), 20 (next to 16 px text, toolbars), 24 (icon on its own), 32 (empty states only) |
+| Stroke | Lucide’s default, scaled with the icon: 1.33 px at 16, 1.67 at 20, 2 at 24 |
+| Grid | 24 × 24, at least 1 unit of padding, round caps and joins |
+| Colour | `currentColor`, with the `color.icon.*` tokens |
+| Next to text | Centred on the first line. The gap follows the text size: 4 px next to 14 px text or smaller, 8 px next to 16 px text or larger |
+| Labels | Icon with a label by default; icon-only for well-known actions, with a name and a tooltip |
+| Decorative icons | Hidden from screen readers (`aria-hidden="true"`) |
+| Contrast | 3:1 or more for icons that carry meaning (WCAG 1.4.11) |
+| Target | 24 × 24 or more (WCAG 2.5.8); icon buttons in products are 32 × 32 |
+| Names | One name per meaning, kebab-case, such as `circle-check` |
+| Package | Lucide for Vue 1.62.0, pinned, imported by name |
+| Right to left | Not needed: products are in Vietnamese and English |
+
+## In this section
+
+| Page | What is in it |
+|---|---|
+| [Library](/foundations/styles/icons/library/) | Every icon. Search, filter and copy a name. |
+| [Usage](/foundations/styles/icons/usage/) | Size, stroke, colour, text alignment, labels, and the icon for each common action. |
+| [Accessibility](/foundations/styles/icons/accessibility/) | Names, decorative icons, tooltips, contrast and target size. |
+| [Code](/foundations/styles/icons/code/) | Installing, importing, sizing and labelling Lucide icons in Vue, with notes for React and Astro. |
+
+## Licence
+
+Lucide is © Lucide Contributors and released under the [ISC licence](https://lucide.dev/license). Parts of it come from Feather, © Cole Bemis, under the MIT licence. Both allow commercial use. Keep the licence notice when you ship the icons. The Lucide package keeps it for you.

package/dist/docs/src/content/foundations/styles/icons/library.mdx

@@ -0,0 +1,19 @@
+---
+title: Library
+description: Every Lucide icon Beehexa can use. Search by name or tag, filter by category, switch the size and click an icon to copy its name.
+order: 1
+---
+import IconBrowser from '../../../../components/IconBrowser.astro';
+
+**Click an icon to copy its name.** Names are kebab-case, such as `circle-check`. In Vue the same icon is `CircleCheck`.
+
+Before you pick an icon, check [Common actions](/foundations/styles/icons/usage/#common-actions): if the meaning is listed there, use that icon. The library opens on the category **Common actions**, which shows only those icons; a search looks through every icon, and **All** lists them all. They are Lucide icons chosen for common Beehexa actions. None is redrawn or renamed.
+
+<IconBrowser />
+
+## Using the library
+
+- Search matches icon names first, then the tags Lucide gives each icon. “Sync” finds `refresh-cw`.
+- The size switch shows 16, 20 and 24 px. Products use 16 px by default.
+- With the keyboard: Tab to the icons, move with the arrow keys, Home and End, and press Enter to copy.
+- Don’t see what you need? Search by meaning as well as by name. Two icons that each make sense alone rarely make a good third one. See [Custom icons](/foundations/styles/icons/code/#custom-icons).

package/dist/docs/src/content/foundations/styles/icons/usage.mdx

@@ -0,0 +1,100 @@
+---
+title: Usage
+description: Which size to use, how stroke, colour and alignment work next to text, when an icon needs a label, and the one icon for each common Beehexa action.
+order: 2
+---
+import IconDemo from '../../../../components/IconDemo.astro';
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+**Use 16 px icons in the colour of the text, with a label, and the same icon for the same meaning everywhere.**
+
+## Sizes
+
+**Pick the size from the text next to the icon.**
+
+| Size | Use it for |
+|---|---|
+| 16 px | Default. Buttons, menus, tables, form fields, next to 14 px text. |
+| 20 px | Next to 16 px text, in toolbars and in the page header. |
+| 24 px | An icon on its own, such as a status in a card or a small empty state. |
+| 32 px | Empty states only. |
+
+Don’t use other sizes. Don’t scale an icon to fit a box: change the box.
+
+<IconDemo kind="dodont" item="size" />
+
+## Stroke
+
+**Keep Lucide’s stroke.** It is 2 units on the 24 grid and scales with the icon: 1.33 px at 16, 1.67 px at 20, 2 px at 24. Don’t set `stroke-width` or `absoluteStrokeWidth`. A fixed 2 px stroke fills in the small details of a 16 px icon.
+
+<IconDemo kind="dodont" item="stroke" />
+
+## Colour
+
+**An icon takes the colour of its text.** Icons draw with `currentColor`, so an icon in a button or a link is right without extra code. Set a colour only with a `color.icon.*` token:
+
+<ColorDemo kind="roles" group="icon" />
+
+- Status icons use the status token, such as `icon.danger`, and always sit next to the status in words.
+- Never give an icon a colour to decorate it, and never use the brand yellow for an icon.
+
+<IconDemo kind="dodont" item="colour" />
+
+## Alignment with text
+
+**Centre the icon on the line height of the text.** Use `display: flex; align-items: center`. Next to several lines, centre the icon on the first line.
+
+<IconDemo kind="align" />
+
+<IconDemo kind="dodont" item="align" />
+
+## Spacing
+
+**The gap between an icon and its text follows the text size: 4 px next to 14 px text or smaller, 8 px next to 16 px text or larger.**
+
+| Text | Icon | Gap | Token | Where |
+|---|---|---|---|---|
+| 12 or 14 px | 16 px | 4 px | `space.050` | Small and default controls, menus, tabs, table cells |
+| 16 px or larger | 20 or 24 px | 8 px | `space.100` | Large controls, toolbars, the page header, a status in a card |
+
+Set the gap on the control with `gap`, not with a margin on the icon.
+
+<IconDemo kind="spacing" />
+
+## Icon and label
+
+**Give an icon a label by default.** The label says what happens; the icon helps people find it again.
+
+Use an icon on its own only when all three are true:
+
+- The action is well known: close, search, add, edit, delete, copy, refresh, settings, filter, more, menu.
+- Space is tight, such as a table row or a toolbar.
+- The button has a name (`aria-label`) and a tooltip with the same words. See [Accessibility](/foundations/styles/icons/accessibility/).
+
+<IconDemo kind="dodont" item="label" />
+
+## Selected state
+
+**Lucide icons are outline only.** Show a selected item with `background.selected` and the indicator bar, not by filling the icon.
+
+<IconDemo kind="dodont" item="selected" />
+
+## Common actions
+
+**One icon per meaning.** Use this icon whenever you show one of these actions or objects, in every product. If a meaning is missing, ask before you choose one, so it is added here.
+
+<IconDemo kind="actions" />
+
+<IconDemo kind="dodont" item="meaning" />
+
+## Do and don’t
+
+| Do | Don’t |
+|---|---|
+| Use 16, 20, 24 or 32 px. | Scale icons to other sizes. |
+| Keep the icon in the text colour. | Colour icons to decorate. |
+| Add a label to most icons. | Use an unfamiliar icon on its own. |
+| Use the same icon for the same meaning. | Use a different icon in each product. |
+| Use outline icons with a selected background. | Fill an icon to show it is selected. |
+| Write the status next to a status icon. | Let an icon or its colour carry the status alone. |
+| Use one icon per button. | Combine two icons into one action. |

package/dist/docs/src/content/foundations/styles/illustration.mdx

@@ -0,0 +1,9 @@
+---
+title: "Illustration"
+description: "Diagrams, illustrations and images that explain Beehexa products."
+order: 14
+planned:
+  - "When to use a diagram, an illustration or a screenshot"
+  - "The diagram style from the brand guide: structured, built on the hexagon grid"
+  - "Empty states and onboarding images"
+---