@beehexa/design-rules 0.0.0-stage → 2611.3.3

package/dist/docs/src/content/foundations/styles/logos/product-logos.mdx

@@ -0,0 +1,56 @@
+---
+title: Product logos
+description: Logos for Beehexa products, starting with HexaSync, and when to use them instead of the company logo.
+order: 3
+audience: product, marketing
+owner: Brand
+updated: 2026-10-23
+---
+import LogoPair from '../../../../components/logos/LogoPair.astro';
+import LogoInUse from '../../../../components/logos/LogoInUse.astro';
+
+## HexaSync
+
+<LogoPair kind="hexasync" name="HexaSync" />
+
+The HexaSync lockup is built exactly like the company lockup: the same icon, the product name in Inter Display at the same weight, 500, the same spacing and the same [clear space](/foundations/styles/logos/using-the-logo/#clear-space). The tail of the “y” hangs below the icon.
+
+All the rules on [Using the logo](/foundations/styles/logos/using-the-logo/) apply: four colour versions, minimum size, misuse.
+
+## Which logo where
+
+| Where | Logo |
+|---|---|
+| Inside the HexaSync web app | HexaSync |
+| HexaSync product pages, connector listings and marketplaces | HexaSync |
+| Company website, contracts, invoices, recruiting, social media | beehexa |
+| Material about several products | beehexa |
+
+Never place the beehexa and HexaSync logos side by side: they share the icon, so the pair reads as a mistake. Pick one by context.
+
+## HexaSync in use
+
+- **App bar:** the dark version on a graphite bar, at the left, linking to the product home.
+- **Sign-in and empty screens:** the colour version, centred above the content.
+- **Marketplaces and connector listings:** the app icon tile with “HexaSync” written as text next to it. Listings crop to a square, so the lockup doesn't fit there.
+
+<LogoInUse only={['app', 'login', 'marketplace']} />
+
+## Icons and containers
+
+A product has no icon of its own. HexaSync uses the Beehexa icon files for its favicon, app icon and avatar, built with the [3-side rule](/foundations/styles/logos/placement-and-containers/#the-icon-in-a-tile-the-3-side-rule). The product name goes in the app name, the page title and the alt text, never inside the icon.
+
+## Spelling
+
+- The company logo is lowercase: “beehexa”.
+- A product logo keeps the product's own spelling: “HexaSync”, one word, capital H and S.
+
+## A new product logo
+
+Every product lockup today uses the Beehexa icon with the product name next to it. To get one for a new product:
+
+1. Write to the Brand owner at [hello@beehexa.com](mailto:hello@beehexa.com?subject=New%20product%20logo) with the product name as it will be written.
+2. Brand builds the lockup from the masters: the icon, the name in Inter Display, outlined, at the chosen weight, with the same spacing.
+3. The files are added to the [package](/foundations/styles/logos/downloads-and-terms/).
+
+Don't draw a product logo yourself, and don't give a product an icon of its own.

package/dist/docs/src/content/foundations/styles/logos/using-the-logo.mdx

@@ -0,0 +1,70 @@
+---
+title: Using the logo
+description: Colour versions, backgrounds, clear space, minimum size, the icon on its own and what not to do.
+order: 1
+audience: everyone who places the logo
+owner: Brand
+updated: 2026-10-23
+---
+import LogoColourVersions from '../../../../components/logos/LogoColourVersions.astro';
+import LogoClearSpace from '../../../../components/logos/LogoClearSpace.astro';
+import LogoMinSize from '../../../../components/logos/LogoMinSize.astro';
+import LogoMisuse from '../../../../components/logos/LogoMisuse.astro';
+
+## Colour versions
+
+Four versions made from three colours: yellow #FCB017, graphite #2B2A28 and white. Pick the one with the most contrast against your background.
+
+<LogoColourVersions />
+
+WCAG does not set a contrast minimum for logos (Understanding 1.4.3 and 1.4.11), but a logo nobody can see is not remembered. We place every version where it stands out, aiming for the 3 : 1 that WCAG sets for other graphics. That is why the yellow icon does not stand alone on a light background; the favicon is the one exception (see [the icon on its own](#the-icon-on-its-own)).
+
+## Clear space
+
+Keep an empty margin of **x** on all four sides: no text, images or page edges inside it. x is the x-height of the wordmark, the height of its lowercase letters, and it is exactly one side of the hexagon. Because x is part of the logo, the margin grows and shrinks with it.
+
+<LogoClearSpace />
+
+The master files already include this margin in their artboard. Align the artboard, not the artwork, and the space comes for free.
+
+## Minimum size
+
+<LogoMinSize />
+
+| | Screen | Print |
+|---|---|---|
+| Lockup, width | 100 px | 25 mm |
+| Icon on its own, height | 16 px | 6 mm |
+
+## Sharp on screen
+
+The icon's edges run at 30°, so on 100% (1×) screens they show stair steps when the logo lands between pixels.
+
+- Give the logo a whole-pixel height and a whole-pixel position.
+- On screen, show the logo as a PNG exported at 3× the size it is shown, not as an SVG. The browser shrinks the larger picture, which softens the edges a little and hides the steps. Every logo on this site, the header included, is drawn this way.
+- To make one, export the master SVG from Figma, Illustrator or Inkscape at 3× the size you need: for a logo 30 px tall, export it 90 px tall and show it at 30 px. A much larger file also works, but it costs more to download and each browser shrinks it a little differently.
+- Never redraw the icon to fit the pixel grid: it breaks the regular hexagon and the 30° angle.
+- In documents, slides and print, use the SVG.
+
+## The icon on its own
+
+Use the icon without the wordmark only where the name is already on screen, or where there is no room for the lockup: favicons, app icons, avatars and small product UI.
+
+| Background | Icon colour |
+|---|---|
+| Dark | Yellow |
+| Light | Graphite, or yellow on a graphite tile |
+| Photo or strong colour | White |
+
+Yellow on white reaches only 1.85 : 1. Next to the wordmark that is fine, because the graphite text carries the logo; on its own the icon would almost disappear. The one exception is the favicon, which is yellow so the browser tab shows the brand colour.
+
+## Misuse
+
+<LogoMisuse />
+
+## Alt text and links
+
+- A logo on its own: alt text “Beehexa”, or the product name, such as “HexaSync”. Don't add the word “logo”.
+- A logo that links to the home page: “Beehexa – Home”, so people know where the link goes.
+- When the name is already written next to the logo, the logo is decorative: use an empty alt text.
+- A logo that is a link needs a visible focus ring, like any other link. The WCAG exemption covers the logo's colours, not the control around it.

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

@@ -0,0 +1,11 @@
+---
+title: Motion
+description: Durations and easing for transitions.
+order: 9
+---
+import TokenTable from '../../../components/TokenTable.astro';
+
+Motion should explain a change, not decorate it. Keep transitions short, and turn off non-essential motion when the user sets `prefers-reduced-motion`.
+
+## Tokens
+<TokenTable prefix="motion" />

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

@@ -0,0 +1,9 @@
+---
+title: "Opacity"
+description: "When transparency is allowed, and why states and disabled controls use colour instead."
+order: 10.5
+planned:
+  - "Where transparency is allowed: the scrim behind dialogs, image overlays"
+  - "Why hover, pressed and disabled use colour steps, not opacity"
+  - "Opacity tokens, if any are needed"
+---

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

@@ -0,0 +1,98 @@
+---
+title: Radius
+description: Eight corner radius steps, which element takes which step, and how to round shapes inside other shapes.
+order: 6
+---
+import ShapeDemo from '../../../components/ShapeDemo.astro';
+import TokenTable from '../../../components/TokenTable.astro';
+
+**Every corner is a radius token. Pick the step by what the element is, then check it against its container.**
+
+## The scale
+
+Eight steps. The token number follows the spacing scale: `radius.100` is 8 px, like `space.100`.
+
+<ShapeDemo kind="radius-scale" />
+
+## Examples
+
+### `radius.0` · square
+
+Edges that touch the screen: the page header, full-width tables and panels that run to the edge.
+
+<ShapeDemo kind="radius-use" item="0" />
+
+### `radius.050` · 4 px
+
+Small things: checkboxes, tags, badges and the items inside a menu.
+
+<ShapeDemo kind="radius-use" item="050" />
+
+### `radius.100` · 8 px
+
+Controls and the small surfaces that open from them: buttons, inputs, selects, menus, popovers, tooltips and alerts. Inputs and buttons always share this value.
+
+<ShapeDemo kind="radius-use" item="100" />
+
+### `radius.150` · 12 px
+
+Cards, and a group of controls with 4 px padding, such as a segmented control.
+
+<ShapeDemo kind="radius-use" item="150" />
+
+### `radius.200` · 16 px
+
+Dialogs and drawers, and a group of controls with 8 px padding.
+
+<ShapeDemo kind="radius-use" item="200" />
+
+### `radius.full` · pill
+
+Avatars, switches and pill-shaped status chips.
+
+<ShapeDemo kind="radius-use" item="full" />
+
+## Shapes inside shapes
+
+**Inner radius = outer radius − padding.** Use it when the padding is smaller than the outer radius. When the padding is larger, the inner element keeps its own radius, as long as it is not larger than the outer one.
+
+<ShapeDemo kind="nesting" />
+
+`radius.025` and `radius.075` exist for these cases only. No component takes them by default.
+
+With the spacing rules, the result is always a step on the scale: 2 px is never padding, and 6 px is padding only inside a component.
+
+When content sits flush inside a box with a 1 px border, clip it with `overflow: hidden`. Don't make a radius − 1 value.
+
+## Focus ring
+
+The focus ring sits 2 px outside the element, and the browser rounds it to match: an 8 px button gets a 10 px ring. No radius token is needed. See [Border](/foundations/styles/border/) for the ring itself.
+
+<ShapeDemo kind="focus-radius" />
+
+## Do and don’t
+
+<ShapeDemo kind="dodont" item="nested" />
+<ShapeDemo kind="dodont" item="controls" />
+<ShapeDemo kind="dodont" item="corners" />
+
+## Code
+
+```css
+.card {
+  border-radius: var(--bh-radius-150);
+  padding: var(--bh-space-050);
+}
+.card img {
+  border-radius: var(--bh-radius-100); /* 12 − 4 = 8 */
+}
+```
+
+## Tokens
+
+<TokenTable prefix="radius" />
+
+## Related
+
+- [Border](/foundations/styles/border/): border widths, the selected bar and the focus ring.
+- [Spacing](/foundations/styles/spacing/): the padding values used in the nesting rule.

package/dist/docs/src/content/foundations/styles/size-and-density.mdx

@@ -0,0 +1,41 @@
+---
+title: Size and density
+description: The three control heights, the size of a target people can click or tap, and how dense Beehexa screens are.
+order: 5
+---
+import LayoutDemo from '../../../components/LayoutDemo.astro';
+import TokenTable from '../../../components/TokenTable.astro';
+
+**Every control comes in three heights: 24, 32 and 40 px. Controls in one row share one height.**
+
+Controls are the things people click or type in: buttons, text fields, selects, segmented controls and tabs. A fixed height keeps a row of them lined up, whatever their text.
+
+<LayoutDemo kind="controls" />
+
+| Size | Height | Where |
+|---|---|---|
+| Small | 24 px | Dense tables and their toolbars, filters, tags |
+| Default | 32 px | Forms, buttons, the header, toolbars, everything else |
+| Large | 40 px | Sign-in and onboarding pages. Optional for the main action on touch screens |
+
+- Keep controls of one height in one row. A 24 px button next to a 32 px field looks misaligned.
+- Set heights with the size tokens, not with padding. The text sits in the middle of the height.
+
+## Target size
+
+**Every control can be clicked in an area of at least 24 × 24 px, and tapped in 44 × 44 px on touch screens.**
+
+- 24 px is the minimum target size of WCAG 2.2 (SC 2.5.8). Every control height meets it.
+- On touch screens, keep the visible height and make the area that responds to a tap at least 44 × 44 px (`size.target.touch`).
+
+## Density
+
+**Beehexa has one density for now: default.**
+
+One density means every screen is designed and checked at one size. A compact density may come later; it would lower control heights and spacing together, and screens that use the tokens will need no change.
+
+Until then, make a dense table with small (24 px) controls and rows, not with smaller spacing tokens.
+
+## Tokens
+
+<TokenTable prefix="size" />

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

@@ -0,0 +1,70 @@
+---
+title: Spacing
+description: A spacing scale of 14 steps on an 8 px base for padding, gaps and margins, and how to choose a step.
+order: 3
+---
+import SpacingDemo from '../../../components/SpacingDemo.astro';
+
+**Every space is a spacing token. Pick the step by how closely two things belong together.**
+
+Things that belong together sit close. Separate groups sit further apart. Readers see the groups before they read a word.
+
+<SpacingDemo kind="anatomy" />
+
+## The scale
+
+**14 steps on an 8 px base. Each step has its own job, shown beside it.**
+
+The token number is a percentage of 8 px: `space.100` is 8 px, `space.200` is 16 px, and `space.075` is 6 px. The steps grow further apart as they get larger, because a 4 px change is clear between small gaps and invisible between large ones.
+
+<SpacingDemo kind="scale" />
+
+When two things could take either of two steps, ask how much they belong together. More related means smaller.
+
+### Padding and gap
+
+<SpacingDemo kind="padding-gap" />
+
+- Padding is the space inside an element. Set it on the element.
+- Gap is the space between elements. Set it on their parent with `gap`, in flex or grid layout.
+- Avoid margins between siblings. They add up where two meet and leave space after the last item; `gap` does neither.
+- Measure padding from the outer edge, border included. A 32 px input with a 1 px border has 11 px of padding inside the border, so its text sits 12 px from the edge.
+
+## The 8 px base
+
+**From 8 px up, every space is a multiple of 4 px. Below 8 px, the scale also has two 2 px steps: 2 and 6 px.**
+
+| Range | Steps | Use |
+|---|---|---|
+| Compact, below 8 px | 2, 4, 6 | Inside components only |
+| From 8 px | 8, 12, 16, 20, 24, 32, 40, 48, 64, 80 | Components, layout and page sections |
+
+- Text line heights are multiples of 4 px too (see [Typography](/foundations/styles/typography/)). Text, controls and spaces line up.
+- Use `space.025` (2 px) only to nudge a small thing into place: a badge on an icon, a status dot beside text. Never use it between controls or as padding.
+- Use `space.075` (6 px) only inside components, in two places: above and below the label of a 32 px control, where (32 − 20) ÷ 2 = 6, and the sides of a tooltip. Never use it for layout, sections or card padding, or between an icon and text: that gap is 4 px next to 14 px text and 8 px next to 16 px text and larger.
+- Borders and focus rings are not spacing. Keep them out of your sums except for padding, as above.
+
+### No negative space
+
+There are no negative spacing tokens.
+
+- When two things overlap, such as a stack of avatars, the component sets the overlap.
+- Do not use a negative margin to pull an element into line. Fix the spacing around it.
+
+## Do and don’t
+
+<SpacingDemo kind="dodont" item="grouping" />
+<SpacingDemo kind="dodont" item="scale" />
+<SpacingDemo kind="dodont" item="nudge" />
+
+## Vietnamese text
+
+Vietnamese text needs taller lines for its accents. The text styles add that height on their own (see [Typography](/foundations/styles/typography/)), so spacing does not change: use the same tokens in both languages.
+
+Vietnamese labels are often longer than English ones. Let them wrap, or give the container room. Do not take space away to make a label fit.
+
+## Related
+
+- [App frame](/foundations/styles/layout/app-frame/): the spacing that lines up the header, side navigation and page header.
+- [Grid](/foundations/styles/layout/grid/): columns, gutters and page margins at each breakpoint.
+- [Size and density](/foundations/styles/size-and-density/): control heights.

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

@@ -0,0 +1,53 @@
+---
+title: Code
+description: Font stacks, getting the fonts, OpenType features for numbers and codes, and the type tokens.
+order: 3
+---
+import TokenTable from '../../../../components/TokenTable.astro';
+import TypeDemo from '../../../../components/TypeDemo.astro';
+
+## Font stacks
+
+Use the tokens, not your own lists.
+
+```css
+/* font.family.sans */
+font-family: Inter, "Noto Sans", system-ui, sans-serif;
+
+/* font.family.mono */
+font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+```
+
+Noto Sans is the fallback because it covers Vietnamese and ₫ and is close to Inter in size (x-height 0.536 em against Inter's 0.546), so a page that falls back keeps its layout.
+
+## Getting the fonts
+
+- **On the web,** self-host the fonts. Use the Inter build from the Google Fonts repository (`github.com/google/fonts`, `ofl/inter`): it is hinted for small text on Windows and keeps every OpenType feature. Don't link the Google Fonts API: its files drop `cv05`, `cv08`, `ss02` and `zero`, and `cv05` and `cv08` are on by default (see [Numbers and codes](#numbers-and-codes)). This site serves those files, cut into Latin, Latin Extended and Vietnamese subsets.
+- **On your computer,** for Figma, slides and documents, install Inter from Google Fonts and JetBrains Mono from JetBrains. The Google Fonts build of Inter also avoids clipped accents in older Windows apps such as Office.
+- Both licences allow use in products, documents and logos.
+
+## Numbers and codes
+
+`cv05` and `cv08` are on for all Inter text. They give lowercase l a tail and uppercase I serifs, so l, I and 1 never look alike in names, IDs and keys. Turn the rest on where they help; leave body text as it is.
+
+- **Tables and changing values:** use tabular figures (`font-variant-numeric: tabular-nums`), so digits line up in columns and counters don't jitter.
+- **Codes people read or type,** such as order numbers, SKUs and API keys: add the slashed zero (`zero`) to Inter, or set them in JetBrains Mono (`code.default`). JetBrains Mono has no `cv05` or `cv08`, so code looks the same.
+
+<TypeDemo kind="numbers" />
+
+<TypeDemo kind="features" />
+
+Every text style is applied with the `font` shorthand, and the shorthand resets `font-feature-settings`. So the features are set on every element from one variable, `--bh-font-features`; to add a feature, change the variable, not the property.
+
+```css
+/* Base: on every element */
+:root { --bh-font-features: "cv05", "cv08"; }
+*, ::before, ::after { font-feature-settings: var(--bh-font-features) !important; }
+
+/* Opt in where needed */
+.table-number { font-variant-numeric: tabular-nums; }
+.code-value  { --bh-font-features: "cv05", "cv08", "zero"; }
+```
+
+## Tokens
+<TokenTable prefix="font" />

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

@@ -0,0 +1,58 @@
+---
+title: Typography
+description: Two typefaces and fourteen text styles, with their weights, letter spacing and line heights.
+order: 2
+sidebarLabel: Overview
+---
+import TypeDemo from '../../../../components/TypeDemo.astro';
+
+## Typefaces
+
+Two typefaces cover everything: Inter for interface and reading text, JetBrains Mono for code.
+
+<TypeDemo kind="faces" />
+
+Inter was chosen because:
+
+- Its tall x-height keeps small interface text legible.
+- It covers Vietnamese in full, the ₫ sign included.
+- It has OpenType features that tell look-alike characters apart, such as l, I and 1, which matters in a product full of order numbers and API keys.
+- It is open source under the SIL Open Font License, so it can be self-hosted and embedded.
+- It is the typeface of the Beehexa wordmark, so product text and logo belong to one family.
+
+Inter has an optical size axis: from 32 px up it draws as Inter Display, with tighter spacing for headings. Browsers apply it on their own; leave `font-optical-sizing` at `auto`.
+
+## Text styles
+
+Text is set with **text styles**, not loose sizes. Each style is one token that carries size, line height, weight and typeface together, named for its role. Fourteen styles in five groups cover every Beehexa product, document and page.
+
+<TypeDemo kind="styles" />
+
+- **Display** is for marketing pages only. Product screens start at `heading.xlarge`.
+- **Heading** styles title pages, sections, cards and groups. Use one `heading.large` per page, as its title.
+- **Body** is for running text. `body.default` (14 px) is the default in product UI; `body.large` (16 px) is for text people read rather than scan.
+- **Label** is for text on or beside controls: buttons, form labels, tabs, menus, badges.
+- **Code** is for code, IDs and keys.
+
+## Weights
+
+| Weight | Token | Use |
+|---|---|---|
+| 400 | `font.weight.regular` | Body text |
+| 500 | `font.weight.medium` | Labels |
+| 600 | `font.weight.semibold` | Headings |
+| 700 | `font.weight.bold` | Display only |
+
+Don't go lighter than 400: thin strokes break up on small text. Bold body text is not a heading; for emphasis that matters to the meaning, use `<strong>` or `<em>`, so screen readers get it too.
+
+## Letter spacing
+
+Leave it at 0. Inter's optical size axis already tightens large text, so headings need no negative tracking, and small text stays at its default spacing.
+
+## Line height
+
+Line heights are part of each text style and sit on the 4 px grid: every one is a multiple of 4 px, so text lines up with spacing and components.
+
+- Body and label styles use 1.3–1.5 times the size (14/20, 12/16, 16/24), which leave room between lines of interface text without spreading a paragraph apart.
+- Headings tighten as they grow, to about 1.1–1.25 for display sizes, so large type stays one block.
+- Vietnamese text uses taller values; see [Vietnamese](/foundations/styles/typography/vietnamese/).

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

@@ -0,0 +1,144 @@
+---
+title: Usage
+description: Which text style each part of a screen uses, and the rules for hierarchy, readability and long text.
+order: 1
+---
+import TypeDemo from '../../../../components/TypeDemo.astro';
+
+## Where each style goes
+
+Product UI uses these styles; component pages name the style each part uses. When a part isn't listed, use the style of the nearest one with the same role.
+
+| Part | Style |
+|---|---|
+| **Page structure** | |
+| Page title | `heading.large` |
+| Section title | `heading.medium` |
+| Breadcrumb | `body.small` |
+| Large title on empty states and onboarding | `heading.xlarge` |
+| **Containers** | |
+| Card, panel and drawer title | `heading.small` |
+| Item title in a grid or list of many cards | `heading.xsmall` |
+| Card description | `body.default` |
+| Dialog title | `heading.medium` |
+| Dialog body | `body.default` |
+| Group title in a form, list or menu | `heading.xsmall` |
+| **Forms** | |
+| Field label | `label.default` |
+| Input text and placeholder | `body.default` |
+| Helper and error text | `body.small` |
+| Checkbox and radio text | `body.default` |
+| **Actions and navigation** | |
+| Button, link button | `label.default` |
+| Small button | `label.small` |
+| Tab, menu item, side navigation item | `label.default` |
+| Top navigation item | `label.default` |
+| **Data** | |
+| Table header | `label.small` |
+| Table cell | `body.default` |
+| Number in a table | `body.default` with tabular figures |
+| ID, SKU, key in a table | `code.default` |
+| Badge, tag, status | `label.small` |
+| Number in a card, such as a KPI | `heading.large` with tabular figures |
+| Label under a number | `body.small` |
+| **Feedback** | |
+| Banner and toast title | `heading.xsmall` |
+| Banner and toast message | `body.default` |
+| Tooltip | `body.small` |
+| Timestamp, meta | `body.small` |
+| **Reading** | |
+| Help article, document, email body | `body.large` |
+| Inline code | `code.default` family at the surrounding size |
+
+<TypeDemo kind="ui" />
+
+## On websites and documentation
+
+Websites and documentation, this site included, use the same styles. Two things differ from product UI: the page title is one step larger, and running text is `body.large`, because people read these pages rather than scan them.
+
+| Part | Style |
+|---|---|
+| **Site header** | |
+| Top navigation item | `label.default` |
+| Search field | `body.default` |
+| Keyboard shortcut hint | `label.small` |
+| Search result title | `label.default` |
+| Search result description | `body.small` |
+| **Sidebar** | |
+| Section | `heading.xsmall` |
+| Group label | `label.small` |
+| Page and sub-page | `label.default` |
+| **Table of contents** | |
+| Title ("On this page") | `heading.xsmall` |
+| Link | `label.default` |
+| **Page** | |
+| Breadcrumb | `body.small` |
+| Page title | `heading.xlarge` |
+| Lede under the title | `body.large` |
+| Section title (`h2`) | `heading.large` |
+| Subsection title (`h3`) | `heading.medium` |
+| Minor title (`h4`) | `heading.small` |
+| Running text and lists | `body.large` |
+| Table text | `body.default` |
+| Table header | `label.small` |
+| Code block | `code.default` |
+| Inline code | `code.default` family at the surrounding size |
+| Card title | `heading.small` |
+| Card text | `body.default` |
+| Status badge | `label.small` |
+| Tabs | `label.default` |
+| Previous and next links | `body.small` label, `heading.small` page name |
+| Footer and page meta | `body.small` |
+
+## Using the styles
+
+In CSS, each style is one `font` declaration:
+
+```css
+.page-title  { font: var(--bh-font-heading-large); }
+.card-title  { font: var(--bh-font-heading-small); }
+.field-label { font: var(--bh-font-label-default); }
+.helper-text { font: var(--bh-font-body-small); }
+.kpi-value   { font: var(--bh-font-heading-large); font-variant-numeric: tabular-nums; }
+```
+
+- Use a style as a whole. Don't take its size and set your own weight or line height: a near-miss style looks like a mistake next to the real one.
+- Don't make a new style for one screen. If a role is missing, add it here first.
+- Set colour separately, with `color.text.*` tokens.
+- Show the selected item, such as the current page or tab, with colour and an indicator bar, not with a heavier weight: a bolder word gets wider and shifts its neighbours.
+- Bold inside text (`<strong>`, `<b>`) is semibold, 600. Weight 700 stays with the display styles.
+- When one row mixes styles, such as an order ID in `code.default`, a badge and an amount in `body.default`, align the text on its baseline (`vertical-align: baseline`, or `align-items: baseline` in flex), not on the middle. Each style sits differently in its line height, so centring them puts the letters at different heights.
+
+
+## Sizes on small screens
+
+- Product styles keep their size on every screen. Text that changes size between breakpoints makes dense screens harder to learn.
+- Display styles step down below 768 px (`breakpoint.md`): `display.large` and `display.medium` become `display.small`, and `display.small` becomes `heading.xlarge`.
+- All sizes are in `rem`, so text follows the reader's browser setting and zoom.
+
+## Hierarchy
+
+- One page title (`h1`) per page. Go down the heading levels in order, without skipping one.
+- Mark up structure with headings, not with bold or larger paragraphs.
+- Show importance with size and weight first. Don't rely on color alone.
+
+## Readability
+
+- Keep lines to about 100 characters or fewer: put long text on a Narrow page (see [Page widths](/foundations/styles/layout/page-widths/)).
+- Align text to the left, ragged right. Don't justify it; center only short, standalone text.
+- Write in sentence case. Don't set text in all caps: it is slower to read, and in Vietnamese the marks crowd the line above.
+- Use italics sparingly, for titles and terms.
+
+## Long text
+
+Order names, URLs and IDs have no length limit.
+
+- Truncate one-line text with an ellipsis, and always give another way to read the full value, such as a tooltip or a detail view.
+- Let long unbroken strings, such as URLs and keys, break anywhere rather than overflow.
+- Never truncate text people need to finish a task.
+
+## Accessibility
+
+- Text needs a contrast of at least 4.5 : 1 with its background; large text (24 px, or 18.66 px bold) at least 3 : 1. See [Color](/foundations/styles/color/).
+- Set sizes in `rem` and never block zoom, so text can grow to 200% (WCAG 1.4.4).
+- Don't put text in images. Real text scales, translates and reads aloud.

package/dist/docs/src/content/foundations/styles/typography/vietnamese.mdx

@@ -0,0 +1,46 @@
+---
+title: Vietnamese
+description: Taller line heights for Vietnamese text, and how to keep its marks from being cut off.
+order: 2
+---
+import TypeDemo from '../../../../components/TypeDemo.astro';
+
+**Vietnamese text gets taller line heights, so its stacked marks never touch the line above or get cut off.**
+
+Text marked `lang="vi"` gets taller line heights. Vietnamese stacks two marks on some capitals, such as Ấ, Ổ and Ẫ, so they rise well above the other letters. At English line heights those marks touch the line above and are cut off in one-line elements that clip their overflow, such as truncated table cells and button labels.
+
+Line height is the space from one line to the next, so it shows on text of two lines or more. Each shaded band below is one line:
+
+<TypeDemo kind="leading" />
+
+The Vietnamese layer changes line height only; size, weight and typeface stay the same. Each value is the smallest multiple of 4 px that keeps every Vietnamese letter inside its own line box, so marks neither touch the line above nor get clipped.
+
+| Style | English | Vietnamese |
+|---|---|---|
+| `display.large` | <span class="type-num">72/80</span> | <span class="type-num">72/108</span> |
+| `display.medium` | <span class="type-num">60/68</span> | <span class="type-num">60/88</span> |
+| `display.small` | <span class="type-num">48/56</span> | <span class="type-num">48/72</span> |
+| `heading.xlarge` | <span class="type-num">32/40</span> | <span class="type-num">32/48</span> |
+| `heading.large` | <span class="type-num">24/32</span> | <span class="type-num">24/40</span> |
+| `heading.medium` | <span class="type-num">20/28</span> | <span class="type-num">20/32</span> |
+| `heading.small` | <span class="type-num">16/24</span> | <span class="type-num">16/24</span> (same) |
+| `heading.xsmall` | <span class="type-num">14/20</span> | <span class="type-num">14/24</span> |
+| `body.large` | <span class="type-num">16/24</span> | <span class="type-num">16/24</span> (same) |
+| `body.default` | <span class="type-num">14/20</span> | <span class="type-num">14/24</span> |
+| `body.small` | <span class="type-num">12/16</span> | <span class="type-num">12/20</span> |
+| `label.default` | <span class="type-num">14/20</span> | <span class="type-num">14/24</span> |
+| `label.small` | <span class="type-num">12/16</span> | <span class="type-num">12/20</span> |
+| `code.default` | <span class="type-num">14/20</span> | <span class="type-num">14/20</span> (same) |
+
+Each box below is one line that clips its overflow, with the line box outlined.
+
+<TypeDemo kind="vietnamese" />
+
+- **Mark the language.** Set `lang="vi"` on `<html>` for a Vietnamese page, or on the element that holds Vietnamese text. Text marked with another language inside it, such as `lang="en"`, goes back to the English values.
+- **Use the tokens.** The text style tokens switch on their own under `lang="vi"` (`:lang(vi)` in `tokens.css`). Code that can't read CSS variables, such as an Ant Design Vue theme, takes the `vi` values from `tokens.js`.
+- **Let components grow.** A control or row that sets a fixed height must fit the Vietnamese line height: a 14 px label needs 24 px of line, so set heights from padding plus line height, not as a fixed number.
+- **Don't clip text vertically.** Avoid `overflow: hidden` on a box with no vertical padding; when you must truncate, clip horizontally and let the line box hold the marks.
+- **Test with this string** in every component and state: **ỔN ĐỊNH · ẤN ĐỘ · ẪM · Ở ĐÂY CÓ ƯU ĐÃI**.
+
+JetBrains Mono draws Vietnamese marks inside its own line box, so `code.default` keeps 14/20. This site serves its Vietnamese subset too, so Vietnamese in code doesn't fall back to another typeface.
+