@beehexa/design-rules 0.0.0-stage → 2611.3.3

package/dist/docs/src/content/foundations/styles/interaction-states.mdx

@@ -0,0 +1,49 @@
+---
+title: Interaction states
+description: How controls look when hovered, focused, pressed, selected or disabled.
+order: 10
+---
+import TokenTable from '../../../components/TokenTable.astro';
+
+Every interactive element needs all of these states. Each state has its own colour token, so every component shows it the same way and it works in light and dark without extra code.
+
+## The rules
+
+1. Every state uses its own token. Find the token of the element at rest, then add the state: `color.background.neutral` at rest becomes `color.background.neutral.hover` on hover and `color.background.neutral.pressed` when pressed.
+2. Never draw a state with opacity, a transparent overlay, `filter: brightness()` or a mixed colour. The result changes with whatever is under the element, and its contrast can't be checked.
+3. Never invent a hover or pressed colour. If the token you need doesn't exist, ask for it to be added to the Color page first.
+4. Keyboard focus is always visible, on every element that can take focus. Hover is never the only way to show something.
+
+## Each state
+
+| State | When | Background | Text and icon | Border |
+| --- | --- | --- | --- | --- |
+| Rest | Nothing is happening. | The token for the element, such as `color.background.neutral` or `color.background.danger.bold` | The paired text token (see Color, Pairing) | `color.border` or `color.border.bold` |
+| Hover | A pointer is over the element. | The same token plus `.hover`: one step up the scale | Unchanged | Unchanged |
+| Pressed | The element is being clicked or tapped. | The same token plus `.pressed`: two steps up | Unchanged | Unchanged |
+
+The primary button is the one exception. It rests on graphite 12, the last step, so it has no step above: on hover it moves one step back (graphite 11) and when pressed two steps back (graphite 10). Its tokens already do this.
+| Focus | The element has keyboard focus (`:focus-visible`). | Unchanged | Unchanged | Add a ring: `outline: var(--bh-border-width-focused) solid var(--bh-color-border-focus); outline-offset: var(--bh-state-focus-offset);` |
+| Selected | The element is chosen, like a table row, a tab or a menu item. | `color.background.selected`, and `color.background.selected.hover` on hover | Unchanged, and a second cue: a check, the yellow indicator bar (`color.border.selected`) or bold text in a menu | Unchanged |
+| Disabled | The element cannot be used now. | `color.background.disabled` | `color.text.disabled`, `color.icon.disabled` | `color.border.disabled` |
+
+## Rows, menu items and ghost buttons
+
+Elements with no fill at rest use `color.background.neutral.subtle`, which is transparent. On hover they take `color.background.neutral.subtle.hover`; when pressed, `color.background.neutral.subtle.pressed`.
+
+## Disabled
+
+- Use the three disabled colour tokens above. Don't lower the opacity.
+- Remove the pointer and keyboard interaction (`disabled` on native controls, `aria-disabled="true"` plus blocked events on others) and show `cursor: not-allowed`.
+- WCAG doesn't require contrast for disabled controls, so the disabled colours are light on purpose.
+- Prefer telling people why something can't be used, for example in helper text, over a silent disabled control.
+
+## Dark theme
+
+The same tokens work in dark. In dark, fills get lighter on hover and when pressed instead of darker, and the primary button moves back from graphite 12 the same way; the tokens already do this, so the code doesn’t change.
+
+## Tokens
+
+The colours are on the [Color](/foundations/styles/color/) page. The focus ring width, `border.width.focused`, is on the [Border](/foundations/styles/border/) page. This group holds the gap between a control and its ring.
+
+<TokenTable prefix="state" />

package/dist/docs/src/content/foundations/styles/layout/app-frame.mdx

@@ -0,0 +1,81 @@
+---
+title: App frame
+description: The header, side navigation and page header that repeat on every page, their sizes, and the spacing that lines them up.
+order: 1
+---
+import LayoutDemo from '../../../../components/LayoutDemo.astro';
+
+**The header, the side navigation and the page header repeat on every page, in the same place and at the same size.**
+
+## Header
+
+**48 px high, across the full width. It holds what belongs to the whole product.**
+
+| Part | Value |
+|---|---|
+| Height | 48 px: a 32 px control with 8 px above and below. The 1 px line under the header is not counted |
+| Holds | Menu button (below 1024 px), logo, global search, workspace switcher, notifications, account |
+| Does not hold | The breadcrumb and page actions. They change with the page, so they go in the page header |
+
+Use the package token `layout.header.height` (`--bh-layout-header-height`) for this dimension.
+The sidebar widths below are `layout.sidebar.expanded` and `layout.sidebar.collapsed`.
+Convert source units at numeric framework API boundaries instead of copying their values.
+
+## Side navigation
+
+**280 px open, a 64 px rail when collapsed, a drawer below 1024 px. Every Beehexa product uses the same widths.**
+
+| Window | Side navigation |
+|---|---|
+| Below 1024 px | Hidden. The menu button in the header opens it as a drawer over the page. |
+| 1024 px and up | Open at 280 px. People can collapse it to the 64 px rail, and the choice is remembered. |
+
+- **280 px** fits a label of about 31 characters at 14 px, long Vietnamese labels included.
+- **The same width in every product**, so the page starts in the same place when people move between products.
+- **No resizing.** One width keeps products alike. A resizable panel would also need a way to resize it without dragging (WCAG 2.5.7).
+- **The rail** shows icons only. Each label appears in a tooltip.
+
+### Long labels
+
+<LayoutDemo kind="navlabels" />
+
+1. Write a shorter label first.
+2. If it still does not fit, cut it with an ellipsis and show the full label in a tooltip, only when it is cut.
+3. Never widen the side navigation for one label. A product whose labels are long everywhere may set one width between 240 and 320 px for the whole product, and writes it down.
+
+## Page header
+
+**The top of every page: breadcrumb, title, status and page actions.**
+
+<LayoutDemo kind="pageheader" />
+
+| Row | Holds | When |
+|---|---|---|
+| Breadcrumb | The pages above this one | Below the top level |
+| Title row | The page title (`heading.large`) and a status on the left; page actions on the right, the main action last | Always |
+| Description | One line about the page | Optional |
+| Tabs or filters | Views of the same page | Optional |
+
+- **The page header spans the whole content area at every page width.** Only the content below it follows [Full, Wide or Narrow](/foundations/styles/layout/page-widths/), so the title and the page actions stay in the same place on every page.
+- The breadcrumb belongs to the page, not to the header: it changes on every page, and the header stays the same.
+- Context for the whole product, such as the workspace, goes in the header.
+
+## Side panel
+
+A panel beside the main content, such as details of a selected row, takes grid columns: 4 of 12 from 1024 px and 3 of 12 from 1440 px. Below 1024 px it opens as a drawer over the page. See the spans on [Grid](/foundations/styles/layout/grid/#spans).
+
+## Spacing of the frame
+
+**Everything in the frame lines up on two edges: 20 px from the window on the left, and the page margin.**
+
+| Between | Space |
+|---|---|
+| The window edge and the logo; the window edge and the side navigation icons | 20 px, `space.250` |
+| The side navigation items and its edges | 8 px, `space.100` |
+| One side navigation item and the next (each 32 px high) | 4 px, `space.050` |
+| The content and the side navigation, the header or the window edge | The page margin: 16, 24 or 32 px ([Grid](/foundations/styles/layout/grid/)) |
+| The breadcrumb and the title | 8 px, `space.100` |
+| The title and the description | 4 px, `space.050` |
+| The page header and the content | 24 px, `space.300` |
+
+A 20 px edge for the logo comes from the side navigation: 8 px of inset plus the 12 px side padding of a 32 px control. The logo then sits right above the icons.

package/dist/docs/src/content/foundations/styles/layout/breakpoints.mdx

@@ -0,0 +1,56 @@
+---
+title: Breakpoints
+description: The four window widths where Beehexa layouts change, what changes at each, and the order to design in.
+order: 4
+---
+import LayoutDemo from '../../../../components/LayoutDemo.astro';
+import TokenTable from '../../../../components/TokenTable.astro';
+
+**The layout changes at three window widths: 768, 1024 and 1440 px. Every screen must also work at 320 px.**
+
+<LayoutDemo kind="breakpoints" />
+
+## What changes
+
+| Breakpoint | From | Windows | What changes |
+|---|---|---|---|
+| `xs` | 0 | Phones and small windows | One fluid layout: 4 columns, gutter and page margin 16 px, content in one column. Side navigation in a drawer. |
+| `md` | 768 px | Tablets, narrow windows | 8 columns. Gutter and page margin 24 px. Side navigation still in a drawer. |
+| `lg` | 1024 px | Laptops, including 1280 and 1366 px screens | 12 columns. Side navigation open at 280 px, or collapsed to the 64 px rail. A side panel next to the main one. |
+| `xl` | 1440 px | Desktops, including 1536 and 1920 px screens | Page margin 32 px. Four cards a row. |
+
+- **Below 768 px is one layout.** Its columns stretch with the window, from 320 to 767 px. A card or a table inside it can still change with the width of its own container, using container queries.
+- **320 px is not a breakpoint.** It is the narrowest window every screen must work in, which is also a 1280 px window zoomed to 400% (WCAG 1.4.10).
+
+## Design order
+
+**Design for desktop first, then fit the screen to smaller windows. Write the CSS from the smallest window up.**
+
+Beehexa products are used mostly on desktop, so their main screens start at the width people use most.
+
+1. Design at 1440 px, and check it at 1280 px.
+2. Fit it to 1024 px, then to 768 px.
+3. Fit it to 360 px, and check it at 320 px.
+
+In code, the base styles are for the smallest window, and each breakpoint adds to them with `min-width`. Fewer rules have to be undone that way.
+
+## Check every screen at
+
+| Window | Why |
+|---|---|
+| 1440 and 1280 px | The desktops and laptops people use most |
+| 1024 px | Just above the point where the side navigation becomes a drawer |
+| 768 px | Tablets, and the switch to 8 columns |
+| About 844 × 390 px | A phone held sideways: wide enough for the tablet layout, but short |
+| 360 and 320 px | Phones, and the narrowest window allowed |
+| 400% zoom | People who enlarge the page |
+
+## Tokens
+
+<TokenTable prefix="breakpoint" />
+
+## Usage
+
+- Write media queries with `min-width`: `@media (min-width: 768px)`.
+- CSS custom properties cannot be used in media queries. Use the pixel values of these tokens.
+- Change the layout at breakpoints, never the spacing tokens or text sizes inside a component.

package/dist/docs/src/content/foundations/styles/layout/grid.mdx

@@ -0,0 +1,87 @@
+---
+title: Grid
+description: A fluid grid of 4, 8 or 12 columns in the main content area, with gutters and page margins from the spacing tokens.
+order: 3
+---
+import LayoutDemo from '../../../../components/LayoutDemo.astro';
+
+**Lay out the main content area on 4 columns on phones, 8 on tablets and 12 from 1024 px.**
+
+<LayoutDemo kind="grid" />
+
+## Columns, gutters and margins
+
+| Window | Columns | Gutter | Page margin |
+|---|---|---|---|
+| Below 768 px | 4 | 16 px | 16 px |
+| 768 to 1023 px | 8 | 24 px | 24 px |
+| 1024 to 1439 px | 12 | 24 px | 24 px |
+| 1440 px and up | 12 | 24 px | 32 px |
+
+The values are spacing tokens: 16 px is `space.200`, 24 px is `space.300` and 32 px is `space.400`. The ranges start at the `md`, `lg` and `xl` breakpoints.
+
+- **12 columns** divide into halves, thirds, quarters and sixths.
+- **4 columns on phones** give two halves or four quarters. **8 on tablets** keep the same halves and quarters with more room.
+- **Gutters** are 16 px on phones and 24 px from 768 px, where there is room to separate cards more clearly.
+- **Page margins** start at 16 px and grow to 32 px on wide screens, so content does not touch the edge of a large window.
+- **Every value is a spacing token and a multiple of 8 px**, like the text line heights, so cards, text and controls line up.
+
+Use the same gutter between rows, so cards are as far apart down as across.
+
+## Fluid columns
+
+**Columns stretch with the window. Gutters and margins stay fixed within each range.**
+
+A wider window gives wider columns, not more empty space. At the next breakpoint the gutter, the margin or the number of columns changes.
+
+## Where the grid sits
+
+**The grid spans the main content area only.**
+
+- The header and the side navigation are not on the grid. The grid starts where the side navigation ends, so its columns always divide the content area.
+- The side navigation keeps a fixed width instead of taking columns. As columns, it would grow and shrink with the window, and collapsing it to the rail would break the column count.
+- Breakpoints still read the window width. Opening or collapsing the side navigation does not change the breakpoint.
+- Content inside a panel or a card can follow the width of its container instead, with container queries.
+- On a wide or narrow page, the grid fills the capped width. See [Page widths](/foundations/styles/layout/page-widths/).
+
+## Spans
+
+A span is the number of columns an item covers.
+
+| Layout | Below 768 px (of 4) | 768 px (of 8) | 1024 px (of 12) | 1440 px (of 12) |
+|---|---|---|---|---|
+| Cards, 1 to 4 a row | 4 | 4 | 4 | 3 |
+| Main panel and side panel | 4 | 8 | 8 + 4 | 9 + 3 |
+| Summary tiles | 2 | 2 | 3 | 2 |
+
+In CSS, the grid is a few lines:
+
+```css
+.page-grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: var(--bh-space-200);
+  padding-inline: var(--bh-space-200);
+}
+@media (min-width: 768px) {
+  .page-grid {
+    grid-template-columns: repeat(8, minmax(0, 1fr));
+    gap: var(--bh-space-300);
+    padding-inline: var(--bh-space-300);
+  }
+}
+@media (min-width: 1024px) {
+  .page-grid { grid-template-columns: repeat(12, minmax(0, 1fr)); }
+}
+@media (min-width: 1440px) {
+  .page-grid { padding-inline: var(--bh-space-400); }
+}
+```
+
+## What goes on the grid
+
+- Page regions align to columns: cards, panels, form columns, tiles.
+- Controls inside a region do not. Inside a card, use spacing tokens.
+- A data table fills its region. Do not split table columns along the grid.
+
+See [Breakpoints](/foundations/styles/layout/breakpoints/) for when the grid changes.

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

@@ -0,0 +1,24 @@
+---
+title: Layout
+description: The frame every Beehexa app shares (header, side navigation, page header and content) and the pages that set its sizes.
+order: 4
+sidebarLabel: Overview
+---
+import LayoutDemo from '../../../../components/LayoutDemo.astro';
+
+**Every Beehexa app uses one frame: a header across the top, side navigation on the left, and the page beside it.**
+
+People move between screens all day. When the menu, the search and the page actions stay in the same place, they find them without looking.
+
+<LayoutDemo kind="anatomy" />
+
+## Where each part is set
+
+| Part | What it sets | Page |
+|---|---|---|
+| Header, side navigation, page header | The parts that repeat on every page, their sizes and the spacing between them | [App frame](/foundations/styles/layout/app-frame/) |
+| Content width | Full, wide or narrow, by what the page holds | [Page widths](/foundations/styles/layout/page-widths/) |
+| Columns | Columns, gutters and page margins inside the content area | [Grid](/foundations/styles/layout/grid/) |
+| Window widths | Where the layout changes, and the order to design in | [Breakpoints](/foundations/styles/layout/breakpoints/) |
+| Control heights | 24, 32 and 40 px, and density | [Size and density](/foundations/styles/size-and-density/) |
+| Space between things | The spacing steps | [Spacing](/foundations/styles/spacing/) |

package/dist/docs/src/content/foundations/styles/layout/overlays.mdx

@@ -0,0 +1,45 @@
+---
+title: Data-inspection overlays
+description: Token-backed sizing and responsive behavior for structured data-inspection drawers and panels.
+order: 5
+---
+
+## Choose by task, not by existing component width
+
+Use a data-inspection overlay when people need record details, structured evidence or related
+configuration while retaining the page context. A short confirmation dialog is not a data-inspection
+overlay and does not inherit this width contract. Prefer the component's standard content sizing
+for short confirmation/action prompts; do not enlarge it just because a data panel uses a wide role.
+
+## Width roles
+
+| Role | Token | When |
+| --- | --- | --- |
+| Default inspection | `layout.overlay.default` | From `breakpoint.lg`: `max(50vw, 900px)` |
+| Wide inspection | `layout.overlay.wide` | Explicit content-heavy variant from `breakpoint.lg`: `70vw` |
+| Mobile inspection | `layout.overlay.mobile` | Below `breakpoint.lg`: `100vw` |
+
+The wide variant is chosen per content/task; it is not a global override for every drawer.
+At the responsive boundary, switch to the mobile role rather than letting the desktop minimum
+force outer-page overflow. Keep the title, close/back control, primary action, error/recovery
+feedback and important content reachable. Long tables/code may scroll inside their own region;
+ordinary text and form labels reflow. Width alone does not prove usable height, keyboard behavior,
+focus containment/return, accessible naming or sticky-action visibility.
+
+Structured desktop descriptions may use `layout.description.minimum` as their nominal minimum
+column width. When the available inline budget is smaller, stack label/value content; the minimum
+must not force horizontal document overflow. This is a description layout role, not a general field,
+modal or page-width token.
+
+## Apply through package exports
+
+Use `--bh-layout-overlay-*` CSS variables in styles, or resolved `tokens.light['layout.overlay.default']`
+when an overlay API expects a CSS length string. Numeric app-frame/page APIs convert source
+`rem` dimensions at their framework boundary. Do not copy these values into a consumer token file.
+The explicit pixel CSS package variant preserves nominal sizes during root-unit migration, not
+an exception from font scaling or responsive behavior.
+
+Header/sidebar and page-cap roles are also source tokens: `layout.header.height`,
+`layout.sidebar.expanded`, `layout.sidebar.collapsed`, `layout.page.narrow`, `layout.page.wide`
+and `layout.page.margin.*`. Their detailed semantics remain in [App frame](/foundations/styles/layout/app-frame/)
+and [Page widths](/foundations/styles/layout/page-widths/). Do not use a page cap as a viewport breakpoint.

package/dist/docs/src/content/foundations/styles/layout/page-widths.mdx

@@ -0,0 +1,38 @@
+---
+title: Page widths
+description: Full, wide or narrow content, picked by what the page holds, and the length of a line of text.
+order: 2
+---
+import LayoutDemo from '../../../../components/LayoutDemo.astro';
+
+**Pick one of three widths for each page, by what the page holds.**
+
+<LayoutDemo kind="widths" />
+
+| Width | Maximum | For |
+|---|---|---|
+| Full | None | Tables, lists, logs, builders and canvases |
+| Wide | 1280 px | Dashboards, detail pages, settings overviews, standard pages |
+| Narrow | 768 px | Forms, settings forms, wizard steps, help and documentation pages |
+
+Wide and Narrow use package tokens `layout.page.wide` and `layout.page.narrow`.
+The responsive margins use `layout.page.margin.small`, `.medium` and `.large`.
+Full has no maximum-width cap; do not replace it with an arbitrarily large numeric token.
+
+- **Full.** Tables and logs show more columns and rows when they use the whole window.
+- **Wide.** Cards and panels stay at a size people can scan on a large monitor.
+- **Narrow.** A form in one column is quick to fill in, and the eye does not travel far from label to field.
+- The maximum is the width of the content. The page margins are outside it.
+- The width applies to the content only. The [page header](/foundations/styles/layout/app-frame/#page-header) above it always spans the whole content area, so the title and the page actions do not move from page to page.
+
+## Alignment
+
+**Centre wide or narrow content in the area beside the side navigation. The page header stays across the full area.**
+
+When the side navigation opens or closes, the page moves to the new centre.
+
+## Running text
+
+**Text runs the full width of its column. To keep lines short enough to read, put long text on a Narrow page.**
+
+A Narrow column of 768 px holds about 100 characters a line of 16 px text. A help or documentation page is a Narrow page; a table of contents beside it is not part of the 768 px.

package/dist/docs/src/content/foundations/styles/logos/downloads-and-terms.mdx

@@ -0,0 +1,65 @@
+---
+title: Downloads and terms
+description: Every logo file, which one to use where, colour codes, the typeface licence and the terms for using the Beehexa trademark.
+order: 5
+audience: designers, developers, partners, press
+owner: Brand
+updated: 2026-10-24
+---
+import LogoHero from '../../../../components/logos/LogoHero.astro';
+
+## The package
+
+<LogoHero />
+
+| Folder | Contents |
+|---|---|
+| `lockups/` | The beehexa and HexaSync lockups in four colour versions each, SVG, with the clear space in the artboard |
+| `icon/` | The icon in yellow, white and graphite, SVG, with clear space |
+| `favicon-web/` | favicon.svg, favicon.ico and PNG favicons at 16, 32 and 48 px, apple-touch-icon, web app icons 192 and 512 px, maskable icon, avatar 800 px, site.webmanifest |
+| `license/` | The SIL Open Font License for Inter |
+| `README.md` | The rules in short |
+
+## Which file to use
+
+| You need | Use |
+|---|---|
+| The logo on a website or in an app | A PNG exported at 3× from `lockups/beehexa-horizontal-1-light.svg` (light backgrounds) or `-2-dark.svg` (dark), shown at 1×. See [sharp on screen](/foundations/styles/logos/using-the-logo/#sharp-on-screen). |
+| The logo in a document, a slide or print | `lockups/beehexa-horizontal-1-light.svg` on light backgrounds, `-2-dark.svg` on dark |
+| The logo on a photo or a strong colour | `-3-white.svg` |
+| One-colour print, engraving, stamps | `-4-graphite.svg` |
+| A favicon | `favicon-web/favicon.svg` and `favicon.ico` |
+| An app icon or a social avatar | `favicon-web/apple-touch-icon.png`, `icon-192.png`, `icon-512.png`, `icon-maskable-512.png`, `avatar-800.png` |
+| The icon in your own layout | `icon/beehexa-icon-*.svg` |
+| A PNG or PDF | Export it from the SVG at the size you need. Never enlarge a small PNG. |
+
+## Colour codes
+
+| Colour | HEX | RGB | Print |
+|---|---|---|---|
+| Yellow | #FCB017 | 252 176 23 | Not set yet |
+| Graphite | #2B2A28 | 43 42 40 | Not set yet |
+| White | #FFFFFF | 255 255 255 | Paper |
+
+CMYK and Pantone values come after a print proof. The 2025 brand guide lists PMS 1235 C for the yellow; check it on paper before using it, because this yellow often prints dull in CMYK on uncoated stock.
+
+## Typeface
+
+The wordmark is set in Inter Display and converted to outlines, so you don't need the font to use the logo. Inter is licensed under the SIL Open Font License 1.1, which allows its use in a logo. The licence is in the package.
+
+## Trademark
+
+The Beehexa logo is registered as a trademark in Viet Nam, no. 4-0358730-000, in classes 9, 35 and 42. Registration of the logo as shown on this site is being confirmed with our industrial property representative.
+
+## Terms of use
+
+> Draft, pending legal review. Questions: [hello@beehexa.com](mailto:hello@beehexa.com?subject=Logo%20use).
+
+You may use the Beehexa and HexaSync logos to refer to Beehexa, to show that your product integrates with HexaSync, or in news and reviews about us, as long as you:
+
+- use the files from the package without changing them, following [Using the logo](/foundations/styles/logos/using-the-logo/);
+- don't suggest that Beehexa sponsors, endorses or partners with you unless we have agreed to it in writing;
+- don't use the logo, the icon or a look-alike in your own product names, logos, domain names, app icons or social accounts;
+- don't make our logo the most prominent element of your material.
+
+We may ask you to change or stop any use of the logos.

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

@@ -0,0 +1,64 @@
+---
+title: Logos
+description: The Beehexa logo and every product logo, with the rules and files to use them on web, print and inside our products.
+order: 12
+sidebarLabel: Overview
+audience: web, print, product UI
+owner: Brand
+updated: 2026-10-23
+---
+import LogoHero from '../../../../components/logos/LogoHero.astro';
+import LogoAnatomy from '../../../../components/logos/LogoAnatomy.astro';
+import LogoConstruction from '../../../../components/logos/LogoConstruction.astro';
+import LogoMeanings from '../../../../components/logos/LogoMeanings.astro';
+
+## Download
+
+<LogoHero />
+
+## Anatomy
+
+The lockup is the icon and the wordmark, side by side. Everything is measured in one unit: the side of the hexagon, which is also the x-height of the wordmark.
+
+<LogoAnatomy />
+
+There are two forms only: this horizontal lockup and the [icon on its own](/foundations/styles/logos/using-the-logo/#the-icon-on-its-own). There is no stacked version.
+
+## Construction
+
+The icon is drawn on a grid of equilateral triangles, so anyone can redraw it exactly: a regular hexagon with a pointy top, three layers and 30° edges.
+
+<LogoConstruction />
+
+## One icon, three meanings
+
+> As a bee builds its hive, Beehexa joins system after system into one solid block, then lifts the business up.
+
+The three meanings sit inside each other: the yellow shows what Beehexa builds, the white shows what it brings.
+
+<LogoMeanings />
+
+## Rules at a glance
+
+| Rule | Value | Details |
+|---|---|---|
+| Forms | Horizontal lockup; icon on its own | [Anatomy](#anatomy) |
+| Colour versions | 4 versions, 3 colours: yellow #FCB017, graphite #2B2A28, white | [Colour versions](/foundations/styles/logos/using-the-logo/#colour-versions) |
+| Clear space | 1 x-height (one hexagon side) on every side | [Clear space](/foundations/styles/logos/using-the-logo/#clear-space) |
+| Minimum size | Lockup 100 px or 25 mm wide; icon 16 px or 6 mm tall | [Minimum size](/foundations/styles/logos/using-the-logo/#minimum-size) |
+| Icon on light backgrounds | Graphite, or yellow on a graphite tile | [The icon on its own](/foundations/styles/logos/using-the-logo/#the-icon-on-its-own) |
+| Spelling | The logo reads “beehexa”, lowercase. Product logos keep the product's spelling: “HexaSync”. In running text, write Beehexa. | [Product logos](/foundations/styles/logos/product-logos/) |
+
+## What changed from the 2018 logo
+
+| | 2018 logo | Refreshed logo |
+|---|---|---|
+| Typeface | Ubuntu, another company's typeface, without Vietnamese letters | Inter Display, Beehexa's typeface, outlined |
+| Wordmark colour | Yellow | Graphite on light backgrounds, white on dark |
+| Icon | No grid; stroke thinner than the gaps (0.8 : 1) | 28-band grid; stroke and gap equal (1 : 1), stroke 11% thicker |
+| Icon to text spacing | No rule | 10 bands, measured from the icon |
+| Clear space | One chevron layer, about 0.22 × the icon height | 1 x-height |
+| Minimum size | 120 px or 30 mm | 100 px or 25 mm |
+| Colour versions | All yellow | 4 versions |
+
+The 2018 logo stays on existing material until the refreshed logo launches. Don't use it in new work.

package/dist/docs/src/content/foundations/styles/logos/placement-and-containers.mdx

@@ -0,0 +1,96 @@
+---
+title: Placement and containers
+description: Where the logo sits on websites, in documents, email, print, on photos and next to partners; how the icon sits in app icons, avatars and favicons; and the mistakes to avoid.
+order: 2
+audience: web, product UI, documents
+owner: Brand
+updated: 2026-10-23
+---
+import LogoInUse from '../../../../components/logos/LogoInUse.astro';
+import LogoContainer from '../../../../components/logos/LogoContainer.astro';
+import LogoMistakes from '../../../../components/logos/LogoMistakes.astro';
+
+## On a website
+
+- Put the lockup at the left of the header and link it to the home page.
+- Size: an icon of 24–32 px in a header 56–64 px tall. This site uses a 24 px icon in a 56 px header.
+- Keep the [clear space](/foundations/styles/logos/using-the-logo/#clear-space) and follow the [sharp on screen](/foundations/styles/logos/using-the-logo/#sharp-on-screen) rules.
+- Inside HexaSync, show the HexaSync logo instead. See [Product logos](/foundations/styles/logos/product-logos/).
+
+<LogoInUse only={['header', 'app']} />
+
+## In documents and slides
+
+- Place the lockup at the top left of the first page or the cover slide, with its clear space.
+- At least 25 mm wide in print.
+- Choose the colour version from the background: version 1 on paper and light slides, version 2 on dark slides.
+
+<LogoInUse only={['document', 'slide']} />
+
+## In email
+
+- Put the lockup under the sender's name, as a PNG exported at 2× and at least 100 px wide. Many email clients don't show SVG.
+- Use alt text “Beehexa”, so the signature still reads when images are blocked.
+
+<LogoInUse only={['email']} />
+
+## In print
+
+- Business cards: the lockup centred on the front, version 2 on graphite; name and details on the back, on white.
+- Keep the lockup at least 25 mm wide and the clear space free of folds, trims and holes.
+
+<LogoInUse only={['card']} />
+
+## On photos and brand colour
+
+- On a photo, use version 3 (white) on a calm area, usually a corner, with its clear space. Never put a box behind the logo to rescue a busy picture: choose another crop.
+- On brand yellow, use version 4 (graphite).
+
+<LogoInUse only={['photo', 'yellow']} />
+
+## Next to a partner logo
+
+When Beehexa appears with a partner, such as on an integration page, use the horizontal lockup. Give both logos the same visual weight, keep each one's clear space, and separate them with a thin vertical line.
+
+<LogoInUse only={['partner']} />
+
+## The icon in a tile: the 3-side rule
+
+App icons and avatars put the icon inside a tile, and platforms crop that tile to a rounded square or a circle. The tile's edge is the boundary, so the icon uses its own rule, measured in hexagon sides:
+
+- The tile is 3 sides wide.
+- The icon is 2 sides tall, two thirds of the tile, centred.
+- That leaves half a side above and below.
+
+<LogoContainer />
+
+| File | Tile | Icon height | Background |
+|---|---|---|---|
+| apple-touch-icon.png | 180 px | 120 px | Graphite #2B2A28 |
+| icon-192.png, icon-512.png | 192 and 512 px | 128 and 341 px | Graphite #2B2A28 |
+| icon-maskable-512.png | 512 px | 341 px, inside the 80% safe circle | Graphite #2B2A28 |
+| avatar-800.png | 800 px | 533 px | Graphite #2B2A28 |
+
+The icon is yellow on a graphite tile: it keeps the brand colour and reaches 7.76 : 1.
+
+## Favicons
+
+The favicon is the icon alone, in yellow, on a transparent background, filling its square.
+
+| File | Sizes | Notes |
+|---|---|---|
+| favicon.svg | Any | Used by current browsers. Smooth edges, drawn from the master icon. |
+| favicon.ico | 16, 32 and 48 px | For older browsers and tools. Each size is drawn large and reduced, which keeps the edges smooth. |
+
+```html
+<link rel="icon" href="/favicon.ico" sizes="48x48">
+<link rel="icon" type="image/svg+xml" href="/favicon.svg">
+<link rel="apple-touch-icon" href="/apple-touch-icon.png">
+<link rel="manifest" href="/site.webmanifest">
+```
+
+<LogoInUse only={['tab', 'avatar']} />
+
+## Common mistakes
+
+<LogoMistakes />