@beehexa/design-rules 2611.3.3 → 2611.4.1

package/dist/docs/src/content/tools/ant-design-vue-theme.mdx

@@ -4,7 +4,11 @@ description: Make Ant Design Vue components use Beehexa design tokens, breakpoin
 order: 3
 ---
 
-Tokens and full rules are available as local `@beehexa/design-tokens` and `@beehexa/design-rules` packages. They are not released to npm yet. There is no exported `/antdv` theme subpath: keep a framework adapter in your application and derive its values from the installed token package.
+`@beehexa/ant-design-vue-tokens` owns the reusable Ant Design Vue 4 adapter.
+Use its typed ESM API and companion CSS, backed by `@beehexa/design-tokens`.
+Frameworks are peers: `ant-design-vue@^4.2.6` and `vue@^3.3.0`; neither is bundled.
+Unreleased `0.0.0` packages use explicit local development references; only the authorized
+release runner stamps real package versions. Do not copy a theme palette into an application.
 
 **Beehexa tokens are the source of truth. Ant Design Vue only reads them.**
 
@@ -13,32 +17,77 @@ This page is the only place where the Beehexa foundations meet Ant Design Vue. T
 ## Usage
 
 ```vue
-<script setup>
-import { tokens } from '@beehexa/design-tokens';
+<script setup lang="ts">
+import { computed, watchEffect } from 'vue';
+import { createAntDesignVueTheme, getAntDesignVuePopupContainer } from '@beehexa/ant-design-vue-tokens';
 import '@beehexa/design-tokens/css';
-
-// The framework adapter selects semantic roles, not a new application palette.
-const theme = {
-  token: {
-    colorPrimary: tokens.light['color.background.neutral.bold'],
-    colorText: tokens.light['color.text'],
-    colorBorder: tokens.light['color.border'],
-    fontFamily: tokens.light['font.family.sans'],
-  },
-};
+import '@beehexa/ant-design-vue-tokens/css';
+
+const props = defineProps<{ dark: boolean; locale: 'en' | 'vi' }>();
+const theme = computed(() => createAntDesignVueTheme({
+  dark: props.dark, locale: props.locale
+}));
+watchEffect(() => {
+  if (typeof document === 'undefined') return;
+  document.documentElement.dataset.theme = props.dark ? 'dark' : 'light';
+  document.documentElement.lang = props.locale;
+});
 </script>
 
 <template>
-  <a-config-provider :theme="theme">
+  <a-config-provider :theme="theme" :get-popup-container="getAntDesignVuePopupContainer">
     <App />
   </a-config-provider>
 </template>
 ```
 
-This light-mode colour/font example is not the complete theme recipe. Apply the mappings below
-in your adapter, resolve `rem` to pixels at numeric API boundaries, and recompute from
-`{ ...tokens.light, ...tokens.dark }` for dark mode and the `tokens.vi` typography alternatives
-for Vietnamese. Read the installed rule documents before implementing states or components.
+`createAntDesignVueTheme({ dark = false, locale = 'en' } = {})` returns
+the native `ThemeConfig`. Recompute on theme/language changes; each call
+returns a fresh object. `locale` selects source typography, not translated AntD messages.
+Pass the appropriate AntD language pack through `ConfigProvider.locale`, and configure the
+date library separately. Render native `useMessage`, `useNotification` and `useModal`
+holders in a feedback host inside the sole root provider. Bind application notify facades
+to those hook APIs; never use detached raw static feedback APIs. The factory sets
+`hashed: false` because AntD4 contextual message/notification holders otherwise retain
+stale hashes across theme/locale changes. Keep an existing notice open while switching
+dark/Vietnamese to light/English; its typography and paint must follow the active theme.
+
+Keep document `data-theme` and `lang` synchronized for teleported overlays. Import
+companion CSS after application/framework styles. Use a native 16px root and 14px body;
+numeric APIs resolve source rem at 16px. The pixel entrypoint is not the dashboard path.
+
+## Overlay ownership and bounded native content
+
+Triggered popups use `getAntDesignVuePopupContainer` to stay inside their nearest native
+Modal/Drawer or custom `data-bh-overlay-owner` host. Native Modal/Drawer roots remain
+body-hosted for viewport geometry. Provider-bound modal facades default their invocation
+`zIndex` through `getAntDesignVueModalZIndex()` while preserving explicit caller values;
+this keeps keyboard/awaited confirmations above their live owner. Nested drawers use
+`getAntDesignVueOverlayZIndex(fullscreen, ownerZIndex)` as `rootStyle.zIndex` so
+surface and mask move together; AntD4's `zIndex` prop styles only the content wrapper.
+Body-teleported fullscreen editors/images and fullscreen native Modals capture
+`getAntDesignVueFullscreenZIndex()` before mounting their root. This combines the
+fullscreen role with above-owner ordering; a fixed450 must not fall below a nested
+native Drawer451. Mark custom roots only once they are active, avoiding self-counting.
+Tour's inline native default also requires its public
+`zIndex` prop bound to `z-index.spotlight`.
+
+The companion CSS provides opt-in native structural contracts, not application selectors:
+
+- `bh-ant-fill-drawer` / `bh-ant-drawer-flush`: bounded body, intrinsic header/footer,
+  optional zero body padding; bind through `rootClassName`.
+- `bh-ant-fill-tabs`: bounded native wrappers and active pane. Nested tabs opt in separately;
+  `bh-ant-fill-tabs--scroll` enables pane scrolling and `bh-ant-tabs-mobile-inset` adds the
+  source mobile inset. Inactive panes stay hidden.
+- `bh-ant-fill-spin` / `bh-ant-fill-card`: carry an existing bounded host through native wrappers.
+- `bh-ant-inspection-descriptions`: source desktop label minimum and mobile stacked rows.
+- `bh-ant-data-table`: generic pending/success/error row classes plus public `customCell`
+  markers `data-bh-cell-interaction="editable|readonly"` and `data-bh-cell-state="changed"`.
+  Native selection outranks operational row paint; changed cells keep diff paint on hover.
+  `bh-ant-table-nowrap` is an independent horizontal-content opt-in.
+
+Keep custom business content and host geometry in the consumer. Do not recreate these
+native selectors through per-page `:deep(.ant-*)`, global overrides or priority escalation.
 
 ## Token mapping
 
@@ -50,6 +99,64 @@ for Vietnamese. Read the installed rule documents before implementing states or
 | `borderRadius` | `radius.100` |
 | `fontFamily` | `font.family.sans` |
 
+The adapter also pins semantic hover/pressed/disabled/link/status/selection/focus roles instead
+of allowing a framework-generated blue palette to leak through. Inputs, selects, checkboxes
+and radios use `color.border.bold` while cards/tables use `color.border`. Layout header and
+sider and mobile navigation drawer share `color.surface.subtle`; there is no separate shell palette or nested isolated
+theme. Use `font.body.default` for table data, `font.label.small` for headers/tags,
+`font.heading.medium` for modal titles and `font.heading.small` for drawer titles.
+
+### Ant Design Vue 4 component contracts
+
+- Table reads `colorFillAlter`, `colorTextHeading`, `controlItemBgActive` and
+  `controlItemBgActiveHover`. AntD5 names such as `headerBg` and `headerColor` are ignored
+  by AntD Vue 4.2.6 and must not be used.
+- Menu reads `colorItem*`, `radiusItem`, `radiusSubMenuItem` and `colorActiveBar*`.
+  Explicit `theme="dark"` menus receive the same source roles. Selection has a visible bar,
+  not a heavier label that shifts its neighbours or merely a changed fill.
+- Form controls share source outline/focus/disabled roles. Validation retains danger/warning
+  text/icons and native state semantics. Do not replace meaningful input borders with divider
+  hairlines.
+- Tag status presets are `success`, `processing`, `warning`, `error`; default is neutral.
+  They use source foreground and outline pairs. Arbitrary hue presets are not status names.
+  Badge counts are neutral; error/processing status dots retain their semantics.
+- Tooltip and Message use the inverse surface/text pair. Modal/Drawer content uses surface,
+  scrim and overlay elevation. Progress is neutral by default and semantic on success/error.
+
+### Companion CSS and structural classes
+
+Use component tokens first. The package CSS fills actual AntD4 gaps: semantic label/header/title
+typography, hard-coded submenu fill, selected bar colors, keyboard focus offsets, safe areas,
+responsive Tour placement, reduced motion and neutral Badge count without recoloring error dots.
+Application selectors and palette overrides belong neither in that CSS nor in a dashboard theme.
+Consumers retain genuine portal layout and scrolling mechanics only. Framework paint
+and typography fixes belong to the package, not duplicated consumer overrides.
+
+`bh-ant-tag-large` on a Tag selects the source large label (24px minimum, 8px inline padding);
+the default is 20px minimum/6px. Both grow for Vietnamese line boxes rather than clipping marks.
+`bh-ant-tree-fill` on a Tree opts into a bounded flex host and virtual-list height; intrinsic
+trees must not use it.
+
+For data inspection, bind `width="var(--bh-ant-overlay-width)"` and apply
+`bh-ant-inspection-modal` or Drawer `rootClassName="bh-ant-inspection-drawer"`.
+Add `bh-ant-inspection-modal--wide` / `bh-ant-inspection-drawer--wide` only for an explicit
+content-heavy variant. The variable selects `layout.overlay.default` / `.wide`, and `.mobile`
+below `breakpoint.lg`. Short confirmations and navigation drawers retain their own widths.
+Fullscreen modes are Modal `wrapClassName="full-screen"` and Drawer
+`rootClassName="fullscreen"`; AntD4 Modal has no `rootClassName` prop. These preserve
+bounded scroll mechanics, not decoration.
+
+### Verify the actual framework
+
+Exercise light/dark × English/Vietnamese with the real CSS imported: buttons and validated
+inputs/selects, ordinary/selected/hovered table row checkboxes, sorting/filter portals,
+expanded/collapsed/horizontal and submenu navigation, form help/error, Tooltip/Message,
+Modal/Drawer and default/wide/fullscreen inspection at 1023/1024px. Check keyboard focus,
+touch hit areas, reduced motion, narrow Tour and focus return. Use
+**ỔN ĐỊNH · ẤN ĐỘ · ẪM · Ở ĐÂY CÓ ƯU ĐÃI** in controls, tags and rows.
+Compilation alone does not establish those rendering/interaction outcomes.
+
+
 ## Spacing
 
 Ant Design Vue sizes come from `sizeUnit` and `sizeStep`. Keep both at 4, so `size` is 16 px. The theme then sets each size from a [spacing](/foundations/styles/spacing/) token.

package/dist/docs/src/content/tools/application-content.mdx

@@ -0,0 +1,42 @@
+---
+title: Application content
+description: Source-backed partner marks, person identities, neutral labels and empty-state illustration containers in product content.
+order: 5
+---
+
+## Identity is not status
+
+A connection name, provider name or person identifies an entity. Use its readable
+name with a neutral themed tag, avatar or logo container. Do not hash names into a
+local colour palette or borrow success/warning/danger roles to distinguish names.
+Use operational status colours only when the displayed value actually represents
+that status. Selected, hovered and focused identities use the ordinary interaction
+roles; the identity does not gain a second competing palette.
+
+## Partner and system marks
+
+Keep actual brand assets and their aspect ratio. Use a neutral `surface.subtle`
+container, a `border` edge when needed, and `text` for textual initials. Do not
+recreate a partner brand by colouring a fallback initial.
+
+| Content part | Source role |
+|---|---|
+| Standard partner-logo tile | `content.partner-logo.size` (40 px) |
+| Contained partner mark | `content.partner-logo.image-size` (28 px maximum) |
+| Person or permission-member avatar | `content.avatar.size` (40 px) |
+| System/provider identity container | `content.identity-mark.size` (44 px) |
+| Contained system/provider glyph | `content.identity-mark.image-size` (24 px) |
+
+These dimensions describe the visual identity, not the interactive target. If the
+identity is actionable, apply the source target-size and focus rules separately.
+A compact text-initial tile may use the normal control size instead of introducing
+a one-off identity dimension. Numeric component/image APIs convert these source
+roles at their boundary; do not duplicate their values in consumer constants.
+
+## Empty states
+
+`content.empty-illustration.size` is a 96 px illustration container. Standard UI
+icons inside it retain the 16/20/24/32 px icon sizes described by the icon guidance;
+the container does not authorize an arbitrary 40 px icon. Use source typography,
+spacing and semantic colours for the explanation and recovery action. Decorative
+illustrations must not be the only explanation that a list is empty or unavailable.

package/dist/docs/src/content/tools/editors.mdx

@@ -0,0 +1,27 @@
+---
+title: Editors and resize controls
+description: Source-backed editor syntax, diff pairs, numeric font boundaries and accessible resize handles.
+order: 6
+---
+
+## Editor canvas and syntax
+
+Editors use `editor.background` and `editor.text`, a theme-aware reading canvas. This is deliberately different from static fenced code blocks (`color.code.background` / `color.code.text`), whose dark canvas has its own paired text. Never combine the editor syntax foregrounds with that static code-block canvas.
+
+Use `editor.syntax.comment`, `.string`, `.number`, `.keyword`, `.type` and `.delimiter` for language tokens. These aliases reuse readable semantic foregrounds on the editor surface in both themes. Syntax coloring names language constructs, not operational status: a green string is not a successful operation. Keep language punctuation and text available without color. Editor gutter, line numbers, selection, line highlight and cursor have their own `editor.*` roles. Selection must retain a caret, native selection range or another non-color cue.
+
+## Diff inspection
+
+Inserted lines use `editor.diff.inserted.background` with the inserted `text` annotation; removed lines use the removed pair. Keep native + / − gutter markers and accessible diff navigation. Do not add transparency to these pairs or interpret a changed value as an application failure. Ordinary code within either line keeps the theme-aware syntax foregrounds.
+
+## Numeric framework APIs
+
+Monaco and similar frameworks require resolved values, not CSS `var()` strings. Resolve the installed token mode (light plus dark overrides, and Vietnamese typography alternatives) at the framework boundary. Convert `rem` dimensions to nominal pixels using 16 px/rem while the consumer uses the package's explicit pixel CSS compatibility entrypoint; do not copy a downstream token table. `editor.font.family`, `.size`, `.lineHeight` and `.weight` carry the complete `font.code.default` recipe (14/20, Vietnamese 14/24). Configure all four, not just font size. Theme definitions must be updated when app mode changes. Preserve legitimate editor settings such as read-only, wrapping, language workers, cancellation and diff layout.
+
+## Resize controls
+
+`resize.divider` is the visible line, not its interaction area. The handle uses `resize.handle.width`, `.height`, `.radius`, `.background`, `resize.color` and `resize.grip`. Hover, focus and drag use `resize.active` on the divider; the handle uses `resize.handle.activeBackground` with `resize.activeGrip`. Keep a visible keyboard focus ring. Extend the hit region to `resize.target` and, for touch, `resize.touchTarget` without moving panel content or changing the visible divider. Keyboard-enabled separators retain orientation, value, min/max and arrow-key behavior. Do not add a decorative transition while dragging.
+
+## Fullscreen and popup ordering
+
+Fullscreen editors, code viewers and image inspection use `z-index.fullscreen` (450) with isolation. Monaco completion, hover and parameter-hint widgets use `z-index.tooltip` (600); ordinary in-page popups keep framework layers inside their owner via the adapter's contextual container. Mark custom fullscreen hosts with `data-bh-overlay-owner`. Native confirmations resolve invocation-time ordering through `getAntDesignVueModalZIndex`, and nested drawers use `getAntDesignVueOverlayZIndex` with their live owner layer. Blocking global loading uses `z-index.loading` (650), below always-visible toast feedback (700). See [Z-index](/foundations/styles/z-index/) for the complete ordering. Avoid a new local z-index scale or a glass effect; custom fullscreen surfaces use semantic surfaces and image inspection uses one `color.surface.scrim` layer. Layering does not replace focus containment, Escape handling, focus return, scroll locking or reachable controls.

package/dist/docs/src/content/tools/mermaid.mdx

@@ -0,0 +1,95 @@
+---
+title: Mermaid and execution diagrams
+description: Source-backed Mermaid configuration, descriptive execution states, interaction and image export.
+order: 6
+---
+
+Use `@beehexa/mermaid-tokens` for every Mermaid initialization. It returns a fresh
+`MermaidConfig` from `@beehexa/design-tokens`; Mermaid remains a peer dependency.
+Pass the active `dark` and `locale` on every render. A theme or language change
+requires rendering again: SVG paint and text measurements do not update from CSS alone.
+
+```ts
+import { createMermaidConfig, createCanvasTheme } from '@beehexa/mermaid-tokens';
+
+mermaid.initialize(createMermaidConfig({ dark: true, locale: 'vi' }));
+const canvas = createCanvasTheme({ dark: true, locale: 'vi' });
+```
+
+The factory secures `theme`, `look`, `themeVariables`, `themeCSS`, `fontFamily`,
+`fontSize` and `htmlLabels` before `layout`. Mermaid 12 appends this secure array
+to its own default security keys. Definition init CSS must not replace rich-card
+token fonts; topology, definition-owned state styles and unrelated layout directives
+remain available. This configuration contract is not a claim that a rendered smoke
+matrix has passed.
+
+## Meaning before colour
+
+`diagram.*` roles describe an operational execution graph, not an explanatory
+brand schematic or a chart series palette. The same roles apply to the drawing,
+its inspector and its exported artifact.
+
+- Default and indeterminate nodes use `node-*` neutral pairs.
+- `state-ran-ok` means **ran without a reported failure**, not a verified business
+  success. Neutral solid paint preserves this distinction from success status,
+  successful HTTP response, and warning. An HTTP response or business outcome
+  still uses the appropriate success/danger role in its own status label.
+- Failed nodes use `fail-*`, with a failure marker and state text.
+- Never-reached nodes use `unreached-*` and an explicit state label; they are not
+  disabled controls. Not-taken branches use `nottaken-*` plus a dashed boundary.
+- Repeat counts use the neutral `badge-*` pair. Repetition alone is not a warning.
+- Category glyphs use `tile-*`. They identify step type, not run state.
+- Selection and hover use `selection-ring` as **separate geometry outside the
+  node boundary**. Never repaint a failed node to indicate that it is selected.
+- Field labels use `code-key`, values `code-value`, on `code-bg`. These descriptive
+  fields are not links. Full code blocks retain the existing `color.code.*` pair.
+
+Always keep labels, markers, shapes or dash patterns: colour alone is not evidence.
+Pair foregrounds only with their named fills. Validate actual SVG text and meaningful
+line contrast in both themes; token existence does not certify a rendered diagram.
+
+## Type, space and interaction
+
+`diagram.node-font` aliases `font.body.default`, including taller Vietnamese lines.
+Use complete source font styles for node labels, inspector titles, metadata and code.
+Do not replace their weight or line height with component-specific recipes. Let
+Vietnamese marks and long labels wrap without clipping. `diagram.padding` is internal
+node padding; `diagram.export-padding` frames fitted/exported drawing bounds. Graph
+coordinates and existing layout topology are not spacing-scale choices.
+
+The adapter's SVG stylesheet also adapts renderer-owned execution-card labels.
+It replaces their inline 11px/650-weight recipes with `font.heading.xsmall` and
+`font.body.small`, and removes category-tile translucent tints and inset shadows.
+`diagram.card-width`, `diagram.tile-size` and `diagram.glyph-size` retain the
+measurable fixed card and symbol geometry; these are not marketing display type.
+This narrowly scoped stylesheet is the framework gap boundary, not permission for
+page CSS to override definition-owned run-state paint.
+Embedded SVG CSS also supplies opaque source edge-label pairs and explicit
+`"cv05", "cv08"` features alongside the complete font shorthand; SVG/export must
+not depend on the document's universal font-feature rule.
+
+Authoring previews use `diagram.preview-height` for both split panels and
+`diagram.minimum-height` for the drawing viewport; fullscreen fills the enclosing
+host instead. Read-only split diagrams retain a zero minimum so they shrink with
+their host. Structured evidence viewers use `diagram.evidence-height`; multiple
+request-body panes use `diagram.evidence-minimum-height` to keep every part reachable.
+
+
+Use a flat opaque sheet. No gradients, glass, decorative animation, animated
+traversal or state transitions. Retain zoom, fit, fullscreen/escape and PNG export
+controls. Interaction must not overwrite definition-owned fill, stroke, dashes or
+failure markers. Controls stay outside the captured SVG host.
+
+## Export the rendered theme
+
+Resolve literal token values when drawing: Mermaid style statements cannot resolve
+CSS variables. Snapshot the rendered theme and opaque canvas background on the SVG
+host. Export the live, fully decorated drawing at its natural bounds with
+`exportPadding`, not the transformed viewport. Preserve the snapshot even if the
+application theme changes before the new drawing lands. Fonts, locale line height,
+state paint and outer selection geometry must survive SVG/PNG capture. A transparent
+image or white sheet behind dark labels is not a valid fallback.
+
+All package source is in `tokens/diagram.json`; consumers must not maintain a
+second palette or copy generated token values. Local package references are for
+local development only until an authorized release exists.

package/dist/docs/src/content/tools/vueflow.mdx

@@ -0,0 +1,121 @@
+---
+title: VueFlow theme
+description: Source-backed operational graph categories, paired themes, fixed geometry and VueFlow 1 integration.
+order: 5
+---
+
+`@beehexa/vueflow-tokens` adapts the authoritative tokens to VueFlow 1. It does not copy
+VueFlow source, bundle Vue, generate graph data, or change relationship direction.
+
+## Install and apply
+
+Install this package, `@beehexa/design-tokens`, Vue 3, and the VueFlow 1 core, controls and
+minimap peers. Load upstream core, theme, controls and minimap CSS in the lazy graph
+entry before adapter CSS; load native design-token CSS once with a 16px root/14px body.
+Local source packages remain private `0.0.0`; that is not a registry release.
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue'
+import { VueFlow } from '@vue-flow/core'
+import { Background } from '@vue-flow/background'
+import { Controls } from '@vue-flow/controls'
+import { MiniMap } from '@vue-flow/minimap'
+import { createVueFlowTheme } from '@beehexa/vueflow-tokens'
+import '@beehexa/design-tokens/css'
+import '@vue-flow/core/dist/style.css'
+import '@vue-flow/core/dist/theme-default.css'
+import '@vue-flow/controls/dist/style.css'
+import '@vue-flow/minimap/dist/style.css'
+import '@beehexa/vueflow-tokens/css'
+
+const props = defineProps<{ dark: boolean; locale: 'en' | 'vi' }>()
+const theme = computed(() => createVueFlowTheme(props))
+// nodes and edges remain application graph data; never recreate their IDs on theme changes.
+</script>
+
+<template>
+  <VueFlow :class="theme.class" :style="theme.style" v-bind="theme.flowOptions">
+    <Background v-bind="theme.background" />
+    <Controls />
+    <MiniMap v-bind="theme.minimap" />
+  </VueFlow>
+</template>
+```
+
+The factory returns scoped variables, viewport bindings typed with `FlowProps` (not deprecated `FlowOptions`), and Background/MiniMap bindings.
+It resolves light plus dark overrides and Vietnamese typography alternatives from the token
+package. Recompute when theme or locale changes. Keep ready/error handlers and fit the graph
+with padding `0.2` when the host becomes measurable or changes size. VueFlow 1's actual
+`fitViewOnInit` option is used; do not pass invented viewport option names.
+
+## Operational categories are not statuses
+
+`flow.category.*` identifies the existing product's node kinds: task blue, dependency red,
+transformation green, validation deep red, push step gold, decision cyan, loop magenta and
+grouped nodes purple. These categorical identities must not be interpreted as success,
+failure or warning. Keep the node's type label and icon; colour is never its sole identity.
+A category colour does not certify the state of an execution.
+
+Each category supplies `foreground`, `background`, `border` and `hover` as an opaque paired
+light/dark role. Use `getNodeColorPalette(category)` for CSS-backed bindings and
+`getNodeColor(nodeType)` for the frame/edge identity. These source roles replace historical
+application-owned palettes, alpha overlays, gradients and palette-adjustment functions.
+Never append hex alpha suffixes to a CSS variable, or lighten a resolved role downstream.
+
+Selection uses `color.border.selected` plus the selected outline; keyboard focus separately
+uses `color.border.focus`, the focused border width and `state.focus.offset`. Errors use the
+danger frame plus dashed/non-colour indication and a readable error label. Selection or focus
+must not overwrite category identity, hide an error, or be conveyed only through colour.
+Resting handles use the neutral icon role. Focus color is reserved for actual focus,
+not an always-on connector decoration.
+
+## Custom content and geometry
+
+Use `getFlowNodeStyles(NodeType, state)` for custom node bodies. It binds semantic fonts,
+spacing, shape, categorical pairs and source dimensions. Keep custom icons, connector logos,
+labels, handles, accessibility semantics and events in the application. Meaningful loading
+indicators may move; decorative node entrances, pulsing identities, rotating idle icons,
+hover transforms, flowing edge dashes, gradients and glass are not part of the theme.
+
+`NODE_DIMENSIONS`, `GRID_SPACING` and `TASK_DATA_LAYOUT` read `tokens/flow.json`. The scoped
+operational matrix is: task, task dependency, task transformation and task data **450×130**;
+three groups **350×130**; validation, transformation and push step **200×130**;
+decision **160×160**, loop **120×120**, profile **240×100**. Do not confuse task-transformation
+cards with individual transformation steps. Rendering, layout and half-dimension centering
+must use the same source. Preserve existing graph coordinates during theme adoption.
+
+Graph layout coordinates, intrinsic sizing, flex/grid mechanics and viewport transforms are
+not palette values. Do not arbitrarily round them to the spacing scale. Category adaptation
+must not mutate the graph's IDs, expansion state, saved positions or relationship semantics.
+
+## Edges, controls and export
+
+`styleTargetEdge(edge, nodes)` preserves the directed edge's target identity on both stroke
+and marker, keeps other edge data, and disables decorative traversal motion. The application
+may retain dashed lines to communicate transformation or conditional semantics. The custom
+edge renderer must consume the supplied stroke rather than replace it with an unrelated
+edge palette. `FLOW_EDGE` centralizes widths, marker size, path radius and handle size.
+
+The CSS companion addresses actual VueFlow core/default nodes, handles, edge labels, selection,
+Controls buttons and MiniMap surfaces. Controls preserve normal, hover, disabled and focus
+states and enlarge to source touch targets for coarse pointers. Import it after upstream CSS;
+remove competing consumer-wide core/controls/minimap paint rules rather than escalating specificity.
+
+Export the current theme and font from the measured graph surface. Do not force a white
+background or independent system-font palette. Preserve snapshot/fit/restore, overlay filtering,
+resolution feedback and capture fallback handling. Check the real exported image, not just a
+successful capture call.
+
+Graph fullscreen uses an isolated local stacking context at `z-index.modal` (400), not
+`z-index.fullscreen` (450), so global inspectors remain above it. Private child chrome
+ordering such as z10/z15 stays inside that context; do not assign global1001/1002
+to graph controls. Verify real inspector/dialog ordering, Escape and focus return.
+
+## Verification
+
+Exercise light and dark, English and Vietnamese, selected plus focused and error nodes,
+long labels, every fixed dimension, target-coloured arrows, zoom/snap/fitting, expanded groups,
+cycles, narrow and fullscreen hosts, ESC exit, Controls, MiniMap and export. Calculate contrast
+for the actual paired foreground/background and meaningful borders in each rendered theme;
+source tokens and typed configuration alone are not accessibility or visual proof.

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

@@ -36,7 +36,7 @@ Focus ring, màu `color.border.focus`, vẽ cách phần tử 2 px về phía ng
 
 ### `border.width.accent` · 4 px
 
-Thanh trạng thái hoặc nhấn mạnh ở một cạnh: alert và banner, dòng bảng bị lỗi, callout và trích dẫn. Hộp vẫn bo đủ bốn góc và thanh chạy theo đường cong.
+Thanh trạng thái hoặc nhấn mạnh ở một cạnh: dòng bảng bị lỗi, callout và trích dẫn. Banner không dùng thanh này mà dùng nền nhạt theo trạng thái (xem [Cách dùng màu](/vi/foundations/styles/color/usage/)). Hộp vẫn bo đủ bốn góc và thanh chạy theo đường cong.
 
 <ShapeDemo kind="border-use" item="accent" />
 
@@ -60,13 +60,13 @@ Không báo trạng thái chỉ bằng màu. Đang chọn và đang focus còn
 ## 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-vi/foundations/styles/color/usage.mdx

@@ -14,8 +14,9 @@ import ColorDemo from '../../../../components/ColorDemo.astro';
 | Tôi cần | Dùng |
 |---|---|
 | Nền trang | `surface.page` |
-| Card, panel, dialog | `surface`, viền `border` |
-| Sidebar, header của bảng, vùng nền nhạt | `surface.subtle` |
+| Card, panel | `surface`, viền `border` |
+| Menu, popover, dialog, drawer | `surface.overlay`; mục bên trong dùng `surface.overlay.hover`, `.pressed`, `.selected` |
+| Header toàn cục và sidebar (cùng bề mặt khung ứng dụng), drawer điều hướng mobile, header của bảng, vùng nền nhạt | `surface.subtle` |
 | Chữ nội dung, tiêu đề, nhãn | `text` |
 | Mô tả, cột phụ của bảng, điều hướng | `text.subtle` |
 | Metadata, mốc thời gian, chữ hướng dẫn, breadcrumb | `text.subtlest` |
@@ -34,7 +35,11 @@ import ColorDemo from '../../../../components/ColorDemo.astro';
 | Lỗi dưới một trường nhập | `text.danger`, `icon.danger` |
 | Banner báo trạng thái | `background.{role}.subtle`, `border.{role}.subtle`, `text`, `icon.{role}` |
 | Trạng thái trong một dòng của bảng | Một [nhãn](#nhãn) |
-| Tooltip, toast | `surface.inverse`, `text.inverse` |
+| Tooltip | `surface.inverse`, `text.inverse` |
+| Toast | `surface.overlay`, `text`, `icon.{role}`, bóng `elevation.shadow.overlay`; không viền |
+| Switch | Bật: `background.neutral.bold`; tắt: `background.neutral`, viền `border.bold`; núm `surface` |
+| Avatar chữ cái đầu | `background.neutral`, `text` |
+| Số thứ tự, số đếm | `background.neutral.bold`, `text.inverse` |
 | Lớp phủ sau dialog hoặc drawer | `surface.scrim` |
 | Khung chờ khi đang tải | `skeleton`, vệt sáng `skeleton.subtle` |
 | Khối code | `code.background`, `code.text` |
@@ -87,7 +92,9 @@ Cảnh báo dùng màu cam, không dùng màu vàng, vì màu vàng là màu th
 |---|---|---|
 | Hình thức | Viền theo `border` của vai trò, chữ theo `text` của vai trò | Nền theo `bold` của vai trò, chữ và icon theo `text.on-bold` |
 | Kích thước | Cao 20 px, padding 6 px; cỡ lớn 24 px, 8 px | Cao 32 px, padding 12 px |
-| Dùng | Nhiều nhãn trên một màn hình: dòng trong bảng, tag | Một nhãn trên mỗi trang: trạng thái chính của trang đó |
+| Dùng | Nhiều nhãn trên một màn hình: trạng thái trong dòng bảng và danh sách | Một nhãn trên mỗi trang: trạng thái chính của trang đó |
+
+Tag không phải là nhãn. Tag là thứ người dùng thêm vào hoặc gỡ ra, như bộ lọc hay từ khóa: cao 24 px, bo góc 4 px, `border` và `text`, có nút gỡ. Nhãn cho biết trạng thái, người dùng không gỡ được.
 
 ## Trạng thái tương tác
 

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

@@ -2,10 +2,79 @@
 title: "Biểu đồ dữ liệu"
 description: "Màu, chữ và quy tắc cho biểu đồ, ô KPI và các cách hiển thị dữ liệu khác."
 order: 13
-planned:
-  - "Bảng màu cho các chuỗi dữ liệu, đủ tương phản ở light và dark"
-  - "Màu trạng thái trong biểu đồ"
-  - "Các loại biểu đồ và khi nào dùng"
-  - "Trục, chú giải, tooltip và định dạng số"
-  - "Biểu đồ dễ tiếp cận: không chỉ dựa vào màu, có phần mô tả bằng chữ"
 ---
+
+## Chọn theo câu hỏi
+
+Dùng biểu đồ đường cho giá trị theo thời gian, đường xu hướng nhỏ chỉ khi đặt cạnh
+giá trị hiện tại, thanh tỷ lệ cho các phần của một tổng đã ghi rõ, và dòng thời gian
+để thể hiện thời điểm thực thi. Vòng sức khỏe phải có cả điểm số và nhận định bằng
+chữ. Không dùng vùng tô trang trí, chuyển sắc, hiệu ứng kính hoặc nhấp nháy lỗi.
+
+## Chỉ số, loại và trạng thái là ba ý nghĩa khác nhau
+
+`visualization.metric.*` định nghĩa các chuỗi vận hành có tên: tổng phiên chạy,
+hoàn tất, thất bại, tỷ lệ thành công, phiên đang chạy, thời gian thực thi trung bình
+và độ sâu hàng đợi. Số lượng và thời gian tự chúng không phải cảnh báo. Luôn hiện
+đơn vị, ngưỡng và tên chỉ số.
+
+`visualization.job-type.*` định danh các loại queue-status, sync-history,
+polling-jobs và generic-jobs, không biểu thị thành công, cảnh báo hay thất bại.
+Các bí danh màu nền tảng tự thích ứng với giao diện sáng và tối. Luôn kèm tên loại
+hoặc biểu tượng riêng. Ở chế độ kết hợp của dòng thời gian, dấu ngoài thể hiện loại
+phiên và dấu trong thể hiện trạng thái; chú giải phải giải thích cả hai. Ở chế độ
+trạng thái, dùng `color.text.success`, `danger`, `info`, `warning` hoặc chữ trung
+tính theo trạng thái thực tế. Giữ nhãn trạng thái và biểu tượng kết quả.
+
+`visualization.priority.1` đến `.5` thể hiện mức khẩn cấp của hàng đợi, luôn ghi
+P1–P5. Độ ưu tiên không phải kết quả thực thi. P1 cao nhất, P5 thấp nhất. Không
+dùng màu ưu tiên để khẳng định thành công hay thất bại.
+
+## Hình học và chữ
+
+Dùng `visualization.line-width`, `sparkline-width`, `grid-width`, `point-radius`
+và `hover-point-radius` cho đường và điểm SVG. Độ dày tính bằng pixel CSS; dùng
+viewBox theo kích thước đo được hoặc nét không co giãn để tránh méo.
+`timeline-track-height` và `activity-track-height` quy định độ dày thanh tỷ lệ.
+`ring-size` là kích thước CSS; `ring-width` là phần trăm theo API Ant Design;
+`ring-gap` tính bằng độ. Chỉ đổi kích thước thành số tại ranh giới API.
+Tọa độ dữ liệu và kích thước vùng chứa đo được vẫn là dữ liệu, không phải token.
+
+`timeline-node-size` và `timeline-node-inner-size` quy định dấu ngoài cho loại và
+dấu trong cho trạng thái. Các biến thể `touch` và `tablet` giữ khả năng đọc, không
+đổi cách mã hóa. `timeline-cluster-size` quy định dấu tổng hợp số lượng; tô viền
+theo loại hoặc trạng thái, giữ số bằng chữ thường trên nền thường, không đặt chữ
+trắng trên màu sáng đã thích ứng với giao diện tối. Vùng tương tác dùng
+`size.target.touch`, độc lập với kích thước dấu nhìn thấy.
+`chart-height`, `chart-initial-width`, `sparkline-height`,
+`sparkline-compact-height` và `sparkline-initial-width` quy định vùng vẽ; chiều rộng
+ban đầu được thay bằng số đo thực tế. `sparkline-point-radius` là bán kính điểm cuối
+nhỏ. Các kích thước này không phải thang dữ liệu hay giá trị trục.
+
+Dùng `font.heading.large` cùng chữ số có độ rộng bằng nhau cho KPI,
+`font.body.small` cho siêu dữ liệu, trục và tooltip; `font.label.small` cho chú giải.
+Dùng `color.border` cho lưới trang trí, `color.text.subtle` cho nhãn và cặp màu nền
+đảo/chữ đảo cho tooltip. Dấu dữ liệu có ý nghĩa cần tương phản ít nhất 3:1 trên nền
+thực tế; chữ thường cần 4,5:1. Kiểm tra từng cặp màu trong từng giao diện, không
+coi việc dùng bí danh là bằng chứng tương phản khi hiển thị.
+
+## Nhãn, định dạng và tương tác
+
+Giữ định dạng số, thời điểm và thời lượng theo ngôn ngữ nhất quán với bảng bên
+cạnh. Hiện đơn vị và khoảng thời gian; giữ ngữ cảnh múi giờ. Không âm thầm đổi số
+đếm thành tỷ lệ hoặc cắt ngắn thời lượng. Chú giải phải đặt tên mọi chuỗi đang hiện;
+chuỗi được chọn cần dấu hiệu ngoài màu sắc. Tooltip phải nằm trong vùng biểu đồ
+và không được là cách duy nhất để đọc giá trị. Cung cấp số tổng hợp hoặc bảng
+cùng dữ liệu bên cạnh và tên biểu đồ cho công nghệ hỗ trợ. Điều khiển chú giải
+bằng bàn phím phải giữ chỉ báo lấy nét rõ ràng.
+
+## Dải đánh giá lưu lượng
+
+`visualization.traffic.{healthy,attention,degraded,critical,unavailable,fault}.{fill,outline}`
+cung cấp cặp màu tô và viền. Healthy là lưu lượng được chấp nhận; attention, degraded
+và critical thể hiện các ngưỡng tỷ lệ yêu cầu bị từ chối tăng dần. Ghi ngưỡng trong
+nhãn hoặc tooltip. Attention và degraded dùng chung màu cảnh báo: phân biệt bằng
+nét đứt và nhãn rõ ràng, không chỉ bằng màu. Unavailable nghĩa là không có yêu cầu
+để đánh giá. Fault là lỗi xử lý yêu cầu nội bộ/máy chủ, không phải ngưỡng tỷ lệ
+đã đo; hiện số lỗi riêng, nhãn hoặc biểu tượng và họa tiết gạch chéo. Lỗi lấy dữ liệu là lỗi riêng. Không đổi
+dữ liệu thiếu thành số không hay kết quả tốt. Dùng `color.text` trên nền tô nhạt.