@beehexa/design-rules 2611.3.2 → 2611.4.1

package/dist/docs/src/components/ZIndexDemo.astro

@@ -0,0 +1,102 @@
+---
+// Illustrations for the Z-index page. Each layer in the figures uses its own z-index token, and its
+// surface and shadow come from the Elevation page, so the drawings stack the way the product does.
+import '../styles/layout.css';
+import '../styles/shapes.css';
+import '../styles/elevation.css';
+import '../styles/zindex.css';
+import { langOf } from '../lib/i18n';
+import ChevronDown from '@lucide/astro/icons/chevron-down';
+import CircleHelp from '@lucide/astro/icons/circle-question-mark';
+import Info from '@lucide/astro/icons/info';
+import CircleAlert from '@lucide/astro/icons/circle-alert';
+
+interface Props {
+  kind: 'stack' | 'screen' | 'dodont';
+  /** dodont: 'toast' | 'inside' | 'scrim'. */
+  item?: string;
+}
+const { kind, item } = Astro.props;
+const vi = langOf(Astro.url.pathname) === 'vi';
+const L = (en: string, viText: string) => (vi ? viText : en);
+const layers = [
+  { id: 'sticky', v: 100, use: L('Sticky table header', 'Header bảng dính') },
+  { id: 'navigation', v: 200, use: L('App header, side navigation', 'Header app, menu bên trái') },
+  { id: 'overlay', v: 300, use: L('Menu, select list, popover', 'Menu, danh sách select, popover') },
+  { id: 'modal', v: 400, use: L('Dialog, drawer, scrim', 'Dialog, drawer, lớp phủ mờ') },
+  { id: 'spotlight', v: 500, use: L('Product tour', 'Tour hướng dẫn') },
+  { id: 'tooltip', v: 600, use: 'Tooltip' },
+  { id: 'toast', v: 700, use: L('Toast, skip link', 'Toast, skip link') },
+];
+const rows = [['#10293', 'ERP', L('Synced', 'Đã đồng bộ')], ['#10294', 'ERP', L('Synced', 'Đã đồng bộ')], ['#10295', L('Accounting', 'Kế toán'), L('Failed', 'Lỗi')]];
+const legend = [
+  ['1', 'z-index.navigation', L('App header', 'Header của app')],
+  ['2', 'z-index.sticky', L('Table header while the table scrolls', 'Header của bảng khi bảng cuộn')],
+  ['3', 'z-index.overlay', L('Menu opened from a button', 'Menu mở từ một nút')],
+  ['4', 'z-index.tooltip', L('Tooltip on an icon button', 'Tooltip trên nút icon')],
+  ['5', 'z-index.toast', L('Toast', 'Toast')],
+];
+---
+
+{kind === 'stack' && (
+  <figure class="zi-stack-fig sh-root">
+    <div class="zi-stack" role="img" aria-label={L('Seven layers stacked from sticky at the bottom to toast at the top', 'Bảy lớp xếp chồng, từ sticky ở dưới cùng tới toast ở trên cùng')}>
+      <span class="zi-plate is-page"><b>Page</b><code>auto</code></span>
+      {layers.map((l, i) => (
+        <span class={`zi-plate is-${l.id}`} style={`--i: ${i + 1}; z-index: var(--bh-z-index-${l.id})`}><b>{l.id}</b><code>{l.v}</code><em>{l.use}</em></span>
+      ))}
+    </div>
+    <figcaption>{L('Each layer covers the ones below it. The step is 100, so a new layer can go between two others.', 'Mỗi lớp che các lớp bên dưới. Các lớp cách nhau 100, nên có thể chèn lớp mới vào giữa hai lớp.')}</figcaption>
+  </figure>
+)}
+
+{kind === 'screen' && (
+  <div class="zi-screen-wrap sh-root">
+    <div class="zi-screen" role="img" aria-label={L('A sync log screen with an app header, a sticky table header, an open menu, a tooltip and a toast, each numbered', 'Màn hình nhật ký đồng bộ có header app, header bảng dính, menu đang mở, tooltip và toast, mỗi phần được đánh số')}>
+      <div class="zi-head"><span class="zi-n">1</span><b>HexaSync</b><span class="zi-head-r"><span class="zi-icon" aria-label="Help"><CircleHelp size={16} aria-hidden="true" /></span></span></div>
+      <div class="zi-body">
+        <div class="zi-toolbar"><span class="sp-btn is-small el-btn-icon">{L('Actions', 'Thao tác')}<ChevronDown size={16} aria-hidden="true" /></span></div>
+        <div class="zi-table">
+          <div class="zi-th"><span class="zi-n">2</span><span>{L('Order', 'Đơn')}</span><span>{L('Destination', 'Đích')}</span><span>{L('Status', 'Trạng thái')}</span></div>
+          {rows.map((r) => <div class="zi-tr"><span>{r[0]}</span><span>{r[1]}</span><span>{r[2]}</span></div>)}
+        </div>
+        <span class="el-menu zi-menu"><span class="zi-n">3</span><span class="is-on">{L('Retry failed', 'Chạy lại đơn lỗi')}</span><span>{L('Export CSV', 'Xuất CSV')}</span></span>
+        <span class="zi-tip"><span class="zi-n">4</span>{L('Help', 'Trợ giúp')}</span>
+        <span class="el-toast is-info zi-toast"><span class="zi-n">5</span><Info size={16} aria-hidden="true" />{L('Retry started', 'Đã bắt đầu chạy lại')}</span>
+      </div>
+    </div>
+    <ol class="zi-legend">
+      {legend.map(([n, token, what]) => <li><span class="zi-n">{n}</span><code>{token}</code><span>{what}</span></li>)}
+    </ol>
+  </div>
+)}
+
+{kind === 'dodont' && (
+  <div class="sp-dd sh-root">
+    {['do', 'dont'].map((side) => (
+      <figure class={`sp-dd-panel is-${side}`}>
+        <figcaption><span aria-hidden="true">{side === 'do' ? '✓' : '✕'}</span> {side === 'do' ? L('Do', 'Nên') : L('Don’t', 'Không nên')}</figcaption>
+        <div class="sp-dd-stage zi-dd">
+          <div class={`zi-mini is-${item} is-${side}`} aria-hidden="true">
+            <span class="el-lines"><i></i><i></i><i></i></span>
+            <div class="el-scrim zi-mini-scrim"></div>
+            <div class="zi-mini-dialog">
+              <b>{L('New sync job', 'Tạo sync job')}</b>
+              {item === 'inside' && <span class="zi-field">{L('Destination', 'Đích')}<span class="zi-input">ERP<ChevronDown size={16} aria-hidden="true" /></span><span class="el-menu zi-mini-list"><span class="is-on">ERP</span><span>{L('Accounting', 'Kế toán')}</span><span>CRM</span><span>{L('Warehouse', 'Kho')}</span></span></span>}
+              {item !== 'inside' && <span class="zi-mini-text">{L('Choose a source and a destination.', 'Chọn nguồn và đích.')}</span>}
+            </div>
+            {item === 'toast' && <span class="el-toast is-danger zi-mini-toast"><CircleAlert size={16} aria-hidden="true" />{L('Connection lost', 'Mất kết nối')}</span>}
+          </div>
+        </div>
+        <p>
+          {item === 'toast' && side === 'do' && L('Give toasts z-index.toast. A toast stays readable while a dialog is open.', 'Cho toast dùng z-index.toast. Toast vẫn đọc được khi đang mở dialog.')}
+          {item === 'toast' && side === 'dont' && L('Don’t give a toast a lower value than the dialog. It ends up under the scrim.', 'Không cho toast giá trị thấp hơn dialog. Nó sẽ nằm dưới lớp phủ mờ.')}
+          {item === 'inside' && side === 'do' && L('Render a list that opens inside a dialog inside the dialog, so it can run past the dialog’s edge.', 'Danh sách mở ra bên trong dialog thì đặt luôn trong dialog, để nó có thể tràn qua mép dialog.')}
+          {item === 'inside' && side === 'dont' && L('Don’t let the dialog clip the list. Raising its z-index does not fix that.', 'Không để dialog cắt mất danh sách. Tăng z-index cũng không sửa được lỗi này.')}
+          {item === 'scrim' && side === 'do' && L('Put the scrim before the dialog. Both use z-index.modal, so the dialog draws on top.', 'Đặt lớp phủ mờ trước dialog. Cả hai dùng z-index.modal, nên dialog được vẽ lên trên.')}
+          {item === 'scrim' && side === 'dont' && L('Don’t put the scrim after the dialog. It dims the dialog too.', 'Không đặt lớp phủ mờ sau dialog. Nó sẽ làm mờ cả dialog.')}
+        </p>
+      </figure>
+    ))}
+  </div>
+)}

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

@@ -36,7 +36,7 @@ The focus ring, in `color.border.focus`, drawn 2 px outside the element (`state.
 
 ### `border.width.accent` · 4 px
 
-A status or emphasis bar on one edge: alerts and banners, a table row with an error, callouts and quotes. The box keeps its radius on all four corners and the bar follows the curve.
+A status or emphasis bar on one edge: a table row with an error, callouts and quotes. Banners don't use it; they use a tinted background (see [Color usage](/foundations/styles/color/usage/)). The box keeps its radius on all four corners and the bar follows the curve.
 
 <ShapeDemo kind="border-use" item="accent" />
 
@@ -60,13 +60,13 @@ Don't show a state with colour alone. Selected and focused also change the width
 ## Code
 
 ```css
-.alert {
+.callout {
   position: relative;
   overflow: hidden;
   border: var(--bh-border-width-default) solid var(--bh-color-border);
   border-radius: var(--bh-radius-100);
 }
-.alert::before {
+.callout::before {
   content: "";
   position: absolute;
   inset: 0 auto 0 0;

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

@@ -14,8 +14,9 @@ import ColorDemo from '../../../../components/ColorDemo.astro';
 | I need | Use |
 |---|---|
 | Page background | `surface.page` |
-| Card, panel, dialog | `surface`, edge `border` |
-| Sidebar, table header, quiet area | `surface.subtle` |
+| Card, panel | `surface`, edge `border` |
+| Menu, popover, dialog, drawer | `surface.overlay`; items inside use `surface.overlay.hover`, `.pressed`, `.selected` |
+| Global header and sidebar (same shell surface), mobile navigation drawer, 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` |
@@ -34,7 +35,11 @@ import ColorDemo from '../../../../components/ColorDemo.astro';
 | 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` |
+| Tooltip | `surface.inverse`, `text.inverse` |
+| Toast | `surface.overlay`, `text`, `icon.{role}`, shadow `elevation.shadow.overlay`; no border |
+| Switch | On: `background.neutral.bold`; off: `background.neutral`, edge `border.bold`; knob `surface` |
+| Avatar with initials | `background.neutral`, `text` |
+| Step number, count | `background.neutral.bold`, `text.inverse` |
 | Layer behind a dialog or drawer | `surface.scrim` |
 | Loading placeholder | `skeleton`, sheen `skeleton.subtle` |
 | Code block | `code.background`, `code.text` |
@@ -87,7 +92,9 @@ Warning is orange, not yellow: yellow is the brand. There is no sixth level; say
 |---|---|---|
 | 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 |
+| Use | Many per screen: status in table rows and lists | One per page: the status the page is about |
+
+A tag is not a label. A tag is something people add or remove, such as a filter or a keyword: 24 px high, radius 4 px, `border` and `text`, with a remove button. Labels show a status; people can't remove them.
 
 ## Interaction states
 

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

@@ -2,10 +2,78 @@
 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"
 ---
+
+## Choose by the question
+
+Use a line chart for a value over time, a compact sparkline only beside its current
+value, a proportional bar for parts of a stated total, and a timeline for when
+executions happened. A health ring must also show its numeric score and a named
+assessment. Do not use decorative area fills, gradients, glass or pulsing failures.
+
+## Metrics, categories and status are different
+
+`visualization.metric.*` defines named operational series: total jobs, completed,
+failed, success rate, active jobs, average execution time and queue depth. Volume
+and duration alone are not warnings. Keep units, thresholds and metric names visible.
+
+`visualization.job-type.*` defines queue-status, sync-history, polling-jobs and
+generic-jobs as categorical identities, never as success/warning/failure. Their
+foundation colour aliases adapt in light and dark. Always pair colour with the
+job-type name or distinct glyph. In combined timeline mode, the outer mark encodes
+job type and the inner mark encodes status; explain both in the legend. In status
+mode, use `color.text.success`, `danger`, `info`, `warning` or neutral text by the
+actual state. Preserve visible status labels and outcome icons.
+
+`visualization.priority.1` through `.5` encode ranked queue urgency, always labelled
+P1–P5. Priority is not an execution outcome. P1 is highest; P5 is lowest. Do not
+reuse a priority colour to claim success or failure.
+
+## Geometry and typography
+
+Use `visualization.line-width`, `sparkline-width`, `grid-width`, `point-radius`
+and `hover-point-radius` for SVG series and markers. Strokes are CSS pixel
+dimensions; use a measured viewBox or non-scaling strokes to avoid distortion.
+`timeline-track-height` and `activity-track-height` set compact proportional tracks.
+`ring-size` is a CSS dimension; `ring-width` is the Ant Design percent-based stroke
+API, and `ring-gap` is degrees. Convert dimensions only at numeric API boundaries.
+Data coordinates and measured container sizes remain data, not design tokens.
+
+`timeline-node-size` and `timeline-node-inner-size` define the outer categorical and
+inner status marks. Their `touch` and `tablet` variants preserve legibility without
+changing the encoding. `timeline-cluster-size` sets an aggregate count mark; paint
+its boundary with the category/status role and keep its count in normal text on a
+normal surface, never white on a theme-adapted bright mark. Use `size.target.touch`
+for the interactive footprint, independent of the visible mark.
+`chart-height`, `chart-initial-width`, `sparkline-height`,
+`sparkline-compact-height` and `sparkline-initial-width` define plotting viewports;
+initial widths are replaced by measured widths. `sparkline-point-radius` is the
+compact endpoint radius. These are not data scales or axis values.
+
+Use `font.heading.large` with tabular figures for KPI values, `font.body.small` for
+metadata, axes and tooltip copy, and `font.label.small` for legend labels.
+Use `color.border` for decorative grids, `color.text.subtle` for labels and the
+surface/inverse text pair for tooltips. A meaningful data mark needs at least 3:1
+against its actual surface; normal text needs 4.5:1. Check actual theme pairs rather
+than assuming an alias proves rendered contrast.
+
+## Labels, formats and interaction
+
+Keep locale-aware number, timestamp and duration formatting consistent with the
+adjacent table. Include units and time range; preserve timezone context. Never
+silently turn a count into a rate or truncate a duration. Legends must name every
+shown series; a selected series needs an indicator other than colour. Tooltips
+must stay inside the chart container and must not be the only way to read values.
+Provide an adjacent numeric summary or table for the same data and an accessible
+chart name. Keyboard-operable legend controls retain visible focus.
+
+## Traffic assessment bands
+
+`visualization.traffic.{healthy,attention,degraded,critical,unavailable,fault}.{fill,outline}`
+provides paired band paints. Healthy means accepted traffic; attention, degraded and
+critical describe increasing rejected-request ratio thresholds. State the thresholds
+in labels or tooltips. Attention and degraded share warning colours: use a distinct
+dash pattern and explicit labels, not colour alone. Unavailable means no requests
+to assess. Fault means internal/backend request-processing errors, not a ratio band;
+show a separate fault count, explicit label/icon and cross-hatching. Fetch failures remain errors, not a band. Never turn missing
+data into zero or a healthy result. Use normal `color.text` for text on subtle fills.

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

@@ -1,12 +1,75 @@
 ---
 title: Elevation
-description: Shadows that show which surfaces sit above others.
+description: "How far a surface seems to sit above the page. It sets items apart, marks what is temporary and points attention at what matters now."
 order: 8
 ---
+import ElevationDemo from '../../../components/ElevationDemo.astro';
 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.
+Elevation is the distance a surface seems to have from the page, shown with a shadow and, in dark mode, a lighter background. It tells people what stands apart from the page, what is temporary, and what needs attention first.
+
+<ElevationDemo kind="hero" />
+
+## How it works
+
+- **Each level is a pair: a background and a shadow.** Use the two tokens of a level together.
+- **The further from the page, the larger and softer the shadow.** A card has a faint shadow; a dialog a deep one.
+- **Three levels only.** If everything floats, nothing stands out.
+
+Elevation shows how high a surface looks. [Z-index](/foundations/styles/z-index/) decides which surface is drawn on top.
+
+| Level | Background | Shadow | Use for |
+|---|---|---|---|
+| Page | `color.surface.page`, `color.surface.subtle` | none | The page, panels, tables, side navigation, headers |
+| Raised | `color.surface` | `elevation.shadow.raised` | Cards |
+| Overlay | `color.surface.overlay` | `elevation.shadow.overlay` | Menus, select lists, popovers, date pickers, toasts |
+| Modal | `color.surface.overlay` | `elevation.shadow.modal` | Dialogs, drawers, full sheets |
+
+## Page
+
+Most of the screen sits on the page with no shadow. Separate panels and tables with a `color.border` border. Side navigation and table headers use `color.surface.subtle`.
+
+<ElevationDemo kind="level" item="page" />
+
+## Raised
+
+For one item people treat as a unit: a sync job, a connection, a dashboard widget. Cards keep their border, because a faint shadow can disappear on a bright screen or in high-contrast mode.
+
+<ElevationDemo kind="level" item="raised" />
+
+## Overlay
+
+For things that open from a control and close again: menus, select lists, popovers. Toasts use the same surface and shadow.
+
+<ElevationDemo kind="level" item="overlay" />
+
+## Modal
+
+For dialogs and drawers that block the page until people finish or cancel. A modal always sits on `color.surface.scrim`, which dims the page and shows it is unavailable.
+
+<ElevationDemo kind="level" item="modal" />
+
+## Dark mode
+
+**The higher the surface, the lighter it is.** A dark shadow barely shows on a dark page, so each level also gets a lighter background: page graphite 1, cards graphite 2, menus and dialogs graphite 3. The token names are the same in both themes.
+
+<ElevationDemo kind="dark" />
+
+## Inside menus and dialogs
+
+Rows inside a floating surface use the overlay state colours, such as `color.surface.overlay.hover`. The page's hover colour would match the menu background in dark mode and disappear. Mark a selected row with a check, not colour alone.
+
+<ElevationDemo kind="states" />
+
+## Do and don’t
+
+<ElevationDemo kind="dodont" item="pair" />
+<ElevationDemo kind="dodont" item="flat" />
+<ElevationDemo kind="dodont" item="own" />
+<ElevationDemo kind="dodont" item="border" />
 
 ## Tokens
+
 <TokenTable prefix="elevation" />
+
+<TokenTable prefix="color.surface.overlay" />

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

@@ -12,15 +12,18 @@ import ColorDemo from '../../../../components/ColorDemo.astro';
 
 **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. |
+| Size | Token | Use it for |
+|---|---|---|
+| 16 px | `size.icon.default` | Default. Buttons, menus, tables, form fields, next to 14 px text. |
+| 20 px | `size.icon.medium` | Next to 16 px text, in toolbars and in the page header. |
+| 24 px | `size.icon.large` | An icon on its own, such as a status in a card or a small empty state. |
+| 32 px | `size.icon.empty` | Empty states only. |
 
 Don’t use other sizes. Don’t scale an icon to fit a box: change the box.
 
+Bind these roles through CSS variables or convert them at numeric icon APIs;
+the documented pixel sizes are not separate consumer constants.
+
 <IconDemo kind="dodont" item="size" />
 
 ## Stroke

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

@@ -7,6 +7,16 @@ 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.**
 
+The global header and side navigation are one continuous shell surface: both use
+`surface.subtle` (`--bh-color-surface-subtle`) in light and dark themes. The mobile
+navigation drawer, including its logo row, uses that same surface. Do not give the
+header `surface` while the sidebar uses `surface.subtle`. Page headers belong to
+the content surface, not this global shell.
+
+In a mobile navigation drawer, the logo row does not shrink. The menu occupies the
+remaining height and scrolls only when its contents do not fit. Do not give a menu
+below a logo row `min-height: 100%`: that adds the logo height to a full-height menu.
+
 ## Header
 
 **48 px high, across the full width. It holds what belongs to the whole product.**

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

@@ -1,9 +1,47 @@
 ---
 title: "Opacity"
-description: "When transparency is allowed, and why states and disabled controls use colour instead."
+description: "How see-through something is. Used only for images inside something turned off and for the scrim behind dialogs. Controls show their state with colour."
 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"
 ---
+import OpacityDemo from '../../../components/OpacityDemo.astro';
+import TokenTable from '../../../components/TokenTable.astro';
+
+Opacity sets how see-through an element is. A faded element lets the background show through, so its colour changes from screen to screen. Beehexa uses opacity in two places only: images inside something turned off, and the scrim behind dialogs.
+
+## Why controls use colour
+
+- **The background shows through.** A faded button looks different on a white card, a yellow banner and a selected row.
+- **Contrast is no longer checked.** A faded colour is a new colour, and text on it may become unreadable.
+- **Opacity multiplies.** A 40% item inside a 40% card ends up at 16%.
+
+The disabled colour tokens, such as `color.text.disabled`, look the same on every background. See [Interaction states](/foundations/styles/interaction-states/).
+
+| I need to | Use |
+|---|---|
+| Fade a logo, avatar or illustration of something turned off | `opacity.disabled` (0.4) on the image |
+| Turn off a button, input, text or icon | The disabled colour tokens |
+| Dim the page behind a dialog or drawer | `color.surface.scrim` |
+| Fade something in or out | Opacity 0 and 1 in an animation, see [Motion](/foundations/styles/motion/) |
+
+## Images that are turned off
+
+Images have their own colours, so no colour token can change them. Fade the image; give the text `color.text.disabled`; keep the card's border. Always say "Turned off" in words as well.
+
+<OpacityDemo kind="tile" />
+
+<OpacityDemo kind="screen" />
+
+## The scrim
+
+The scrim dims the page behind a dialog or drawer, so the dialog is the focus and the page reads as unavailable. It is a colour with transparency built in: graphite at 40% in light mode, black at 60% in dark mode, where a dark page needs more to dim. Use it as it is.
+
+<OpacityDemo kind="scrim" />
+
+## Do and don’t
+
+<OpacityDemo kind="dodont" item="container" />
+<OpacityDemo kind="dodont" item="controls" />
+
+## Tokens
+
+<TokenTable prefix="opacity" />

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

@@ -21,6 +21,13 @@ Controls are the things people click or type in: buttons, text fields, selects,
 - 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.
 
+Two other parts have a fixed size:
+
+| Part | Size |
+|---|---|
+| Switch | 20 px high, 36 px wide; knob 16 px |
+| Avatar | 32 px; 24 px in dense tables and lists |
+
 ## 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.**

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

@@ -37,7 +37,7 @@ Noto Sans is the fallback because it covers Vietnamese and ₫ and is close to I
 
 <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.
+Every text style uses the `font` shorthand, which resets `font-feature-settings`. The source token `font.features` owns `"cv05", "cv08"`; generated token CSS applies `--bh-font-features` universally with `!important`. Consumers import that CSS rather than copy the base rule below. Add features through the variable, not a competing property. Keep a native 16px root and the 14px `font.body.default` role on the body.
 
 ```css
 /* Base: on every element */

package/dist/docs/src/content/foundations/styles/z-index.mdx

@@ -1,9 +1,67 @@
 ---
 title: "Z-index"
-description: "The stacking order of layers: what sits above what, from sticky headers to dialogs and toasts."
+description: "Which element is drawn on top when two overlap. Seven base layers and explicit fullscreen/readiness roles keep floating things in the same order everywhere."
 order: 8.5
-planned:
-  - "Layer names and their order"
-  - "Which layer each overlay uses: dropdown, popover, tooltip, dialog, drawer, toast"
-  - "How layering pairs with elevation"
 ---
+import ZIndexDemo from '../../../components/ZIndexDemo.astro';
+import TokenTable from '../../../components/TokenTable.astro';
+
+Z-index decides which element is drawn on top when two overlap. Beehexa uses seven named base layers instead of free numbers, so a menu never opens behind a dialog and a toast never hides under the scrim.
+
+<ZIndexDemo kind="stack" />
+
+## How it works
+
+- **A higher layer covers a lower one.** Base values run from 100 to 700 in steps of 100, leaving room for explicit fullscreen and readiness roles.
+- **Pick the layer by what the element does**, not by how high a number you need.
+- **A layer only competes with its neighbours.** An element with its own z-index, transform, filter or opacity below 1 starts a new stacking context; nothing inside can rise above it. That is why a list inside a dialog is rendered inside the dialog.
+
+[Elevation](/foundations/styles/elevation/) shows how high a surface looks; z-index makes sure it is drawn on top. A menu needs both.
+
+| Layer | Token | Value | Elevation | Use for |
+|---|---|---|---|---|
+| Sticky | `z-index.sticky` | 100 | Page | Sticky table headers and toolbars |
+| Navigation | `z-index.navigation` | 200 | Page | App header, side navigation |
+| Overlay | `z-index.overlay` | 300 | Overlay | Menus, select lists, popovers |
+| Modal | `z-index.modal` | 400 | Modal | Dialogs, drawers and their scrim |
+| Spotlight | `z-index.spotlight` | 500 | Modal | Product tour, onboarding spotlight |
+| Tooltip | `z-index.tooltip` | 600 | none | Tooltips |
+| Toast | `z-index.toast` | 700 | Overlay | Toasts, the skip link |
+
+## Why this order
+
+- Menus cover the navigation they open from.
+- A modal blocks the whole page, menus included.
+- A tour can point at something inside a dialog.
+- A tooltip explains a control, wherever that control is.
+- A toast reports on the whole app, so nothing covers it.
+
+## On a screen
+
+<ZIndexDemo kind="screen" />
+
+Inside one component, values from 1 to 9 need no token, for example to lift the focused button in a button group.
+
+## Do and don’t
+
+<ZIndexDemo kind="dodont" item="toast" />
+<ZIndexDemo kind="dodont" item="inside" />
+<ZIndexDemo kind="dodont" item="scrim" />
+
+## Tokens
+
+<TokenTable prefix="z-index" />
+
+## Fullscreen and framework integration
+
+The extended roles `z-index.fullscreen` (450) and `z-index.loading` (650) cover editor/code/image takeovers and blocking application readiness respectively. Fullscreen stays below spotlight, tooltip and toast feedback; readiness covers interactive surfaces and tooltips while toast feedback and the skip link remain on top at 700.
+
+A fullscreen operational graph uses `z-index.modal` in an isolated local stacking context, not the editor takeover role. Child graph chrome uses private local ordering, so a global inspector can appear above it.
+
+The Ant Design Vue adapter owns native component stacking: menus and select lists use the overlay band, dialogs and drawers use modal, tooltips use tooltip, and feedback uses toast. Bind its contextual `getPopupContainer` at the root ConfigProvider so a popup inside a dialog, drawer or fullscreen surface is rendered inside its owner, above the owner's scrim. Do not raise every popup globally to compensate for an incorrect container. Mark custom fullscreen hosts with `data-bh-overlay-owner`.
+
+Root native Modal/Drawer surfaces remain in the document body for viewport geometry. Set root modal defaults from the adapter's invocation-time `getAntDesignVueModalZIndex()` (preserving an explicit caller value), and pass the live parent layer to `getAntDesignVueOverlayZIndex(fullscreen, ownerZIndex)` for nested drawers. A child uses the highest owner bound plus one, not a sum of ancestor z-index values; this keeps native confirmations above a fullscreen editor without crossing into the spotlight/feedback tiers.
+
+Monaco's detached hover, completion and parameter-hint widgets use `z-index.tooltip`. Keep the editor takeover isolated so its child chrome cannot cover global feedback. Use one `color.surface.scrim` behind a modal or image inspector, not multiple translucent layers.
+
+Preserve focus containment, focus return, Escape handling and scroll locking. Exercise the actual graph, editor hints, nested menus, inspector and loading stack; numeric ordering alone is not visual or accessibility proof.