@beehexa/design-rules 2611.3.3 → 2611.4.1

package/dist/docs/scripts/color-pairs.mjs

@@ -7,13 +7,17 @@
 
 export const roles = ['danger', 'warning', 'success', 'info'];
 
-const surfaces = ['surface', 'surface.page', 'surface.subtle'];
+const surfaces = ['surface', 'surface.page', 'surface.subtle', 'surface.overlay'];
 const neutralFills = [
   'background.neutral',
   'background.neutral.hover',
   'background.neutral.subtle.hover',
   'background.selected',
   'background.selected.hover',
+  'surface.overlay.hover',
+  'surface.overlay.pressed',
+  'surface.overlay.selected',
+  'surface.overlay.selected.hover',
 ];
 
 /** @type {Array<{ fg: string; on: string[]; min: number }>} */

package/dist/docs/scripts/token-utils.mjs

@@ -92,7 +92,9 @@ export function createTokenModel(flatTokens) {
 }
 
 /** Same selectors and alias-preserving declarations for site and packages. */
-export function renderTokenCss(flatTokens, { pixels = false } = {}) {
+// `scopes` adds .bh-scope-light and .bh-scope-dark for side-by-side light and dark examples on the
+// docs site. The npm package leaves them out.
+export function renderTokenCss(flatTokens, { pixels = false, scopes = false } = {}) {
   const units = (value) => pixels
     ? value.replace(/(-?(?:\d*\.)?\d+)rem\b/g, (_, number) => `${Number(number) * 16}px`)
     : value;
@@ -102,6 +104,14 @@ export function renderTokenCss(flatTokens, { pixels = false } = {}) {
   const viTokens = flatTokens.filter((token) => token.vi !== undefined);
   const vi = viTokens.map((token) => decl(token, token.vi));
   const reset = viTokens.map((token) => decl(token, token.value));
+  // A scope must redeclare every colour-related token: a var() reference is resolved where it is
+  // declared, so inheriting the :root values would keep the page theme. Type tokens stay out, so
+  // lang="vi" still wins.
+  const scopeLight = flatTokens.filter((token) => !token.name.startsWith('font.')).map((token) => decl(token, token.value));
+  const scopeCss = scopes ? [
+    `.bh-scope-light {\n${scopeLight.join('\n')}\n  color-scheme: light;\n}`,
+    `.bh-scope-dark {\n${scopeLight.join('\n')}\n${dark.join('\n')}\n  color-scheme: dark;\n}`,
+  ] : [];
   return [
     '/* Generated from beehexa.design tokens/*.json. Do not edit by hand. */',
     `:root {\n${light.join('\n')}\n}`,
@@ -109,6 +119,11 @@ export function renderTokenCss(flatTokens, { pixels = false } = {}) {
     `@media (prefers-color-scheme: dark) {\n  :root:not([data-theme='light']) {\n${dark.map((line) => `  ${line}`).join('\n')}\n  }\n}`,
     `:lang(vi) {\n${vi.join('\n')}\n}`,
     `[lang]:not(:lang(vi)) {\n${reset.join('\n')}\n}`,
+    ...scopeCss,
+    ...(flatTokens.some(token => token.name === 'font.features') ? [
+      '/* Preserve source character variants through semantic font shorthands. */',
+      '*, ::before, ::after { font-feature-settings: var(--bh-font-features) !important; }',
+    ] : []),
     '',
   ].join('\n');
 }

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

@@ -63,10 +63,10 @@ const descVi: Record<string, string> = {
   'color.background.disabled': 'Nền của control bị vô hiệu.',
   'color.background.brand.subtle': 'Bề mặt và ghi chú thương hiệu.',
   'color.background.brand.bold': 'Nền vàng thương hiệu. Chữ xám ghi bên trên (text.on-brand). Không có nút màu vàng.',
-  'color.surface': 'Card, panel, dialog. Sáng hơn nền trang một bậc ở giao diện tối.',
+  'color.surface': 'Card, panel. Sáng hơn nền trang một bậc ở giao diện tối.',
   'color.surface.page': 'Nền trang.',
-  'color.surface.subtle': 'Sidebar, header của bảng, vùng nền nhạt.',
-  'color.surface.inverse': 'Bề mặt đảo màu: tooltip, toast. Chữ bên trên: text.inverse.',
+  'color.surface.subtle': 'Header toàn cục và sidebar cùng một bề mặt; drawer điều hướng mobile, header của bảng, vùng nền nhạt.',
+  'color.surface.inverse': 'Bề mặt đảo màu: tooltip. Chữ bên trên: text.inverse.',
   'color.surface.scrim': 'Lớp phủ sau dialog và drawer.',
   'color.border': 'Viền mặc định: đường phân cách, card, bảng.',
   'color.border.bold': 'Viền của ô nhập, checkbox và select. 3:1 (WCAG 1.4.11) trên mọi bề mặt và nền trung tính, kể cả dòng được chọn.',
@@ -186,7 +186,7 @@ const statusRoles = [
 // Token reference: every role and component token split into the four parts of its name,
 // color.{property}.{role}.{emphasis}.{state}. A part that is left out takes its default.
 const PROPS = ['text', 'icon', 'link', 'surface', 'background', 'border', 'skeleton', 'code'];
-const ROLES = ['neutral', 'brand', 'danger', 'warning', 'success', 'info', 'inverse', 'disabled', 'page', 'scrim', 'on-bold', 'on-brand', 'background', 'text'];
+const ROLES = ['neutral', 'brand', 'danger', 'warning', 'success', 'info', 'inverse', 'disabled', 'page', 'overlay', 'scrim', 'on-bold', 'on-brand', 'background', 'text'];
 const EMPHASIS = ['subtle', 'subtlest', 'bold'];
 const STATES = ['hover', 'pressed', 'selected', 'focus'];
 const SCALE_NAMES = Object.keys(scaleNames);
@@ -427,7 +427,7 @@ const actions = [
 {kind === 'labels' && (
   <div class="c-labels">
     <figure class="c-label-set">
-      <figcaption><b>{L('Label', 'Nhãn')}</b> · {L('outlined, for tags and statuses inside tables, lists and cards', 'có viền, cho tag và trạng thái trong bảng, danh sách và card')}</figcaption>
+      <figcaption><b>{L('Label', 'Nhãn')}</b> · {L('outlined, for statuses inside tables, lists and cards', 'có viền, cho trạng thái trong bảng, danh sách và card')}</figcaption>
       <div class="c-label-row">
         <span class="bh-label">{L('Default', 'Mặc định')}</span>
         <span class="bh-label is-brand">Early access</span>

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

@@ -0,0 +1,196 @@
+---
+// Illustrations for the Elevation page. Every surface is a colour token and every shadow an
+// elevation token, so each figure shows the real values. Pins point at the part a token sets,
+// as on the Radius and Border pages. bh-scope-light / bh-scope-dark force a theme for side-by-side views.
+import '../styles/layout.css';
+import '../styles/shapes.css';
+import '../styles/elevation.css';
+import { langOf } from '../lib/i18n';
+import Pin from './ShapePin.astro';
+import Check from '@lucide/astro/icons/check';
+import ChevronDown from '@lucide/astro/icons/chevron-down';
+import Info from '@lucide/astro/icons/info';
+
+interface Props {
+  kind: 'hero' | 'level' | 'dark' | 'states' | 'dodont';
+  /** level: 'page' | 'raised' | 'overlay' | 'modal'. dodont: 'pair' | 'flat' | 'own' | 'border'. */
+  item?: string;
+}
+const { kind, item } = Astro.props;
+const vi = langOf(Astro.url.pathname) === 'vi';
+const L = (en: string, viText: string) => (vi ? viText : en);
+const jobs = [
+  ['Store A → ERP', L('Running · 2 min ago', 'Đang chạy · 2 phút trước')],
+  ['Store B → ' + L('Accounting', 'Kế toán'), L('Paused', 'Tạm dừng')],
+];
+const levels = [
+  { id: 'raised', name: 'Raised', token: 'shadow.raised', use: L('Cards', 'Card') },
+  { id: 'overlay', name: 'Overlay', token: 'shadow.overlay', use: L('Menus, popovers, toasts', 'Menu, popover, toast') },
+  { id: 'modal', name: 'Modal', token: 'shadow.modal', use: L('Dialogs, drawers', 'Dialog, drawer') },
+];
+const menuRows = [L('Run now', 'Chạy ngay'), L('Pause', 'Tạm dừng'), L('Edit mapping', 'Sửa mapping')];
+---
+
+{kind === 'hero' && (
+  <div class="el-hero sh-root">
+    <figure class="el-view">
+      <div class="el-front" aria-hidden="true">
+        <span class="el-plate is-page"><b>Page</b></span>
+        {levels.map((l) => <span class={`el-plate is-${l.id}`}><b>{l.name}</b></span>)}
+      </div>
+      <figcaption>{L('From the front: the shadow grows with the height.', 'Nhìn từ trước: càng cao, bóng càng lớn.')}</figcaption>
+    </figure>
+    <figure class="el-view">
+      <div class="el-side" aria-hidden="true">
+        {levels.slice().reverse().map((l) => (
+          <span class={`el-bar is-${l.id}`}><i></i><code>{l.token}</code><em>{l.use}</em></span>
+        ))}
+        <span class="el-ground"><code>color.surface.page</code></span>
+      </div>
+      <figcaption>{L('From the side: three heights above the page.', 'Nhìn từ cạnh: ba độ cao so với mặt trang.')}</figcaption>
+    </figure>
+  </div>
+)}
+
+{kind === 'level' && item === 'page' && (
+  <div class="sh-ex-grid is-one sh-root">
+    <div class="sh-ex el-ex">
+      <Pin solid label={`${L('Border', 'Viền')}: color.border`} at="bottom" len="300" wide>
+        <div class="sh-frame" role="img" aria-label={L('A table panel on the page, with a border and no shadow', 'Một panel bảng nằm trên trang, có viền và không có bóng')}>
+          <header>{L('Sync logs', 'Nhật ký đồng bộ')}</header>
+          <div class="sh-table">
+            <span><em>10:42:07</em>{L('Order #10293 to ERP', 'Đơn #10293 sang ERP')}<em>{L('Synced', 'Đã đồng bộ')}</em></span>
+            <span><em>10:42:11</em>{L('Order #10295 to ERP', 'Đơn #10295 sang ERP')}<em>{L('Synced', 'Đã đồng bộ')}</em></span>
+          </div>
+        </div>
+      </Pin>
+    </div>
+  </div>
+)}
+
+{kind === 'level' && item === 'raised' && (
+  <div class="sh-ex-grid is-one sh-root">
+    <div class="sh-ex el-ex is-pin-left">
+      <Pin solid label={`${L('Shadow', 'Bóng')}: elevation.shadow.raised`} at="bottom" len="300">
+        <Pin solid label={`${L('Background', 'Nền')}: color.surface`} at="inside-left" inset="100" len="1000">
+          <div class="el-card"><b>{jobs[0][0]}</b><span>{jobs[0][1]}</span></div>
+        </Pin>
+      </Pin>
+    </div>
+  </div>
+)}
+
+{kind === 'level' && item === 'overlay' && (
+  <div class="sh-ex-grid is-one sh-root">
+    <div class="sh-ex el-ex is-top is-pin-left">
+      <div class="el-anchor">
+        <span class="sp-btn el-btn-icon">{L('Actions', 'Thao tác')}<ChevronDown size={16} aria-hidden="true" /></span>
+        <Pin solid label={`${L('Shadow', 'Bóng')}: elevation.shadow.overlay`} at="bottom" len="300">
+          <Pin solid label={`${L('Background', 'Nền')}: color.surface.overlay`} at="inside-left" inset="050" len="1000">
+            <span class="el-menu">{menuRows.map((r, i) => <span class={i === 0 ? 'is-on' : undefined}>{r}</span>)}</span>
+          </Pin>
+        </Pin>
+      </div>
+    </div>
+    <div class="sh-ex el-ex is-pin-left">
+      <Pin solid label={`${L('Shadow', 'Bóng')}: elevation.shadow.overlay`} at="bottom" len="300">
+        <Pin solid label={`${L('Background', 'Nền')}: color.surface.overlay`} at="inside-left" inset="100" len="1000">
+          <span class="el-toast is-info"><Info size={16} aria-hidden="true" />{L('Sync started for 3 jobs', 'Đã bắt đầu đồng bộ 3 job')}</span>
+        </Pin>
+      </Pin>
+    </div>
+  </div>
+)}
+
+{kind === 'level' && item === 'modal' && (
+  <div class="sh-ex-grid is-one sh-root">
+    <div class="sh-ex el-ex el-modal-ex is-pin-left">
+      <div class="el-page" aria-hidden="true">
+        <span class="el-lines"><i></i><i></i><i></i></span>
+        <div class="el-scrim"></div>
+      </div>
+      <Pin solid label={`${L('Shadow', 'Bóng')}: elevation.shadow.modal`} at="bottom" len="300">
+        <Pin solid label={`${L('Background', 'Nền')}: color.surface.overlay`} at="inside-left" inset="100" len="1000">
+        <div class="el-dialog" role="img" aria-label={L('A dialog over the dimmed page', 'Một dialog nằm trên trang đã bị phủ mờ')}>
+          <b>{L('Delete connection?', 'Xoá kết nối?')}</b>
+          <span>{L('Sync history is kept for 30 days.', 'Lịch sử đồng bộ được giữ 30 ngày.')}</span>
+          <span class="el-actions"><span class="sp-btn">{L('Cancel', 'Huỷ')}</span><span class="sp-btn is-primary">{L('Delete', 'Xoá')}</span></span>
+        </div>
+        </Pin>
+      </Pin>
+      <span class="el-scrim-pin"><Pin solid label={`${L('Background', 'Nền')}: color.surface.scrim`} at="bottom" len="200"><i class="el-dot"></i></Pin></span>
+    </div>
+  </div>
+)}
+
+{kind === 'dark' && (
+  <div class="el-themes is-stack sh-root">
+    {['light', 'dark'].map((mode) => (
+      <figure class={`el-theme bh-scope-${mode}`}>
+        <figcaption>{mode === 'light' ? 'Light' : 'Dark'}</figcaption>
+        <div class="el-theme-stage">
+          <Pin solid label={`${L('Background', 'Nền')}: color.surface.page`} at="corner" len="200"><span class="el-dot is-page"></span></Pin>
+          <Pin solid label={`${L('Background', 'Nền')}: color.surface`} at="inside-left" inset="100" len="1000">
+            <div class="el-card is-wide"><b>{jobs[0][0]}</b><span>{jobs[0][1]}</span></div>
+          </Pin>
+          <Pin solid label={`${L('Background', 'Nền')}: color.surface.overlay`} at="inside-left" inset="050" len="1000">
+            <span class="el-menu">{menuRows.slice(0, 2).map((r) => <span>{r}</span>)}</span>
+          </Pin>
+        </div>
+      </figure>
+    ))}
+  </div>
+)}
+
+{kind === 'states' && (
+  <div class="el-themes is-stack sh-root">
+    {['light', 'dark'].map((mode) => (
+      <figure class={`el-theme bh-scope-${mode}`}>
+        <figcaption>{mode === 'light' ? 'Light' : 'Dark'}</figcaption>
+        <div class="el-theme-stage is-col">
+          <span class="el-menu is-list" role="img" aria-label={L('A list of destinations with a hovered row and a selected row', 'Danh sách điểm đích có một dòng đang được rê chuột và một dòng đang chọn')}>
+            <span>CRM</span>
+            <Pin solid label={`${L('Background', 'Nền')}: color.surface.overlay.hover`} at="inside-left" inset="050" len="1000"><span class="is-on">Marketplace</span></Pin>
+            <Pin solid label={`${L('Background', 'Nền')}: color.surface.overlay.selected`} at="inside-left" inset="050" len="1000"><span class="is-sel">ERP<Check size={16} aria-hidden="true" /></span></Pin>
+            <span>{L('Warehouse', 'Kho')}</span>
+          </span>
+        </div>
+      </figure>
+    ))}
+  </div>
+)}
+
+{kind === 'dodont' && (
+  <div class="sp-dd sh-root">
+    <figure class="sp-dd-panel is-do">
+      <figcaption><span aria-hidden="true">✓</span> {L('Do', 'Nên')}</figcaption>
+      <div class:list={['sp-dd-stage', { 'bh-scope-dark': item === 'pair' }]}>
+        {item === 'pair' && <span class="el-menu">{menuRows.map((r, i) => <span class={i === 1 ? 'is-on' : undefined}>{r}</span>)}</span>}
+        {item === 'flat' && <div class="el-panel"><b>{L('Sync logs', 'Nhật ký đồng bộ')}</b><span>{L('128 orders today', '128 đơn hôm nay')}</span></div>}
+        {item === 'own' && <span class="el-menu">{menuRows.map((r) => <span>{r}</span>)}</span>}
+        {item === 'border' && <span class="el-menu">{menuRows.map((r) => <span>{r}</span>)}</span>}
+      </div>
+      <p>
+        {item === 'pair' && L('Inside a menu, use the overlay state colours, such as color.surface.overlay.hover.', 'Bên trong menu, dùng màu trạng thái của overlay, ví dụ color.surface.overlay.hover.')}
+        {item === 'flat' && L('Keep panels, tables and page sections flat. A border is enough to separate them.', 'Để panel, bảng và các phần của trang phẳng. Một đường viền là đủ để tách chúng.')}
+        {item === 'own' && L('Use the shadow token for the level. It changes with the theme.', 'Dùng token bóng của đúng mức. Token tự đổi theo theme.')}
+        {item === 'border' && L('Let the surface and the shadow set the menu apart.', 'Để nền và bóng tách menu khỏi trang.')}
+      </p>
+    </figure>
+    <figure class="sp-dd-panel is-dont">
+      <figcaption><span aria-hidden="true">✕</span> {L('Don’t', 'Không nên')}</figcaption>
+      <div class:list={['sp-dd-stage', { 'bh-scope-dark': item === 'pair' }]}>
+        {item === 'pair' && <span class="el-menu is-wrong-surface">{menuRows.map((r, i) => <span class={i === 1 ? 'is-on' : undefined}>{r}</span>)}</span>}
+        {item === 'flat' && <div class="el-panel is-shadowed"><b>{L('Sync logs', 'Nhật ký đồng bộ')}</b><span>{L('128 orders today', '128 đơn hôm nay')}</span></div>}
+        {item === 'own' && <span class="el-menu is-own">{menuRows.map((r) => <span>{r}</span>)}</span>}
+        {item === 'border' && <span class="el-menu is-bordered">{menuRows.map((r) => <span>{r}</span>)}</span>}
+      </div>
+      <p>
+        {item === 'pair' && L('Don’t use the page’s hover colour inside a menu. In dark mode it is the same colour as the menu, so the hovered row disappears.', 'Không dùng màu hover của trang bên trong menu. Ở dark mode, màu này trùng với nền menu nên dòng đang rê chuột biến mất.')}
+        {item === 'flat' && L('Don’t give every panel a shadow. When everything floats, nothing stands out.', 'Không cho panel nào cũng có bóng. Khi mọi thứ đều nổi thì không còn gì nổi bật.')}
+        {item === 'own' && L('Don’t write your own shadow or stack two tokens. It stays dark grey in dark mode and matches no level.', 'Không tự viết bóng hay chồng hai token. Bóng tự viết không đổi theo theme và không khớp mức nào.')}
+        {item === 'border' && L('Don’t add a border to a menu, popover or dialog.', 'Không thêm viền cho menu, popover hay dialog.')}
+      </p>
+    </figure>
+  </div>
+)}

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

@@ -72,7 +72,7 @@ const bands = bps.map((b, i) => ({ ...b, size: (bps[i + 1]?.min ?? b.min + 480)
           <rect class="f-mark" x={1280 - pad.desktop} y={header} width={pad.desktop} height={800 - header} />
           <rect class="f-mark" x={sidebar} y={header} width={1280 - sidebar} height={pad.desktop} />
           <rect class="f-mark" x={sidebar} y={800 - pad.desktop} width={1280 - sidebar} height={pad.desktop} />
-          <rect class="f-plain" x="0" y="0" width="1280" height={header} />
+          <rect class="f-subtle" x="0" y="0" width="1280" height={header} />
           <rect class="f-line" x="0" y={header - 2} width="1280" height="2" />
           <rect class="f-indicator" x="20" y="12" width="24" height="24" rx="6" />
           <rect class="f-skel" x="52" y="16" width="88" height="16" rx="4" />

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

@@ -0,0 +1,95 @@
+---
+// Illustrations for the Opacity page. Transparency comes only from opacity.disabled and
+// color.surface.scrim; everything else is a colour, border or size token.
+import '../styles/layout.css';
+import '../styles/shapes.css';
+import '../styles/elevation.css';
+import '../styles/opacity.css';
+import Pin from './ShapePin.astro';
+import { langOf } from '../lib/i18n';
+
+interface Props {
+  kind: 'screen' | 'tile' | 'scrim' | 'dodont';
+  /** dodont: 'container' | 'controls'. */
+  item?: string;
+}
+const { kind, item } = Astro.props;
+const vi = langOf(Astro.url.pathname) === 'vi';
+const L = (en: string, viText: string) => (vi ? viText : en);
+const on = L('Connected', 'Đã kết nối');
+const off = L('Turned off', 'Đã tắt');
+const conns = [['ST', 'Store A', 'a', true], ['ER', 'ERP', 'b', true], ['AC', L('Accounting', 'Kế toán'), 'c', false], ['MK', 'Marketplace', 'd', true], ['CR', 'CRM', 'e', false], ['WH', L('Warehouse', 'Kho'), 'f', true]] as const;
+const users = [['LN', 'Linh Nguyen', 'Admin', true], ['TP', 'Tuan Pham', 'Editor', true], ['MH', 'Mai Ho', L('Viewer · deactivated', 'Viewer · đã vô hiệu'), false]] as const;
+---
+
+{kind === 'screen' && (
+  <div class="op-wrap" role="img" aria-label={L('Connections with two turned off, and a team list with one deactivated member', 'Danh sách kết nối có hai kết nối đã tắt, và danh sách thành viên có một người đã bị vô hiệu')}>
+    <span class="op-label">{L('Connections', 'Kết nối')}</span>
+    <div class="op-grid">
+      {conns.map(([code, name, tone, isOn]) => (
+        <div class={isOn ? 'op-tile' : 'op-tile is-off'}>
+          <span class="op-tile-top"><span class={`op-logo is-${tone}`}>{code}</span><span class="op-switch"></span></span>
+          <b>{name}</b><span class="op-status">{isOn ? on : off}</span>
+        </div>
+      ))}
+    </div>
+    <span class="op-label">{L('Team members', 'Thành viên')}</span>
+    <div class="op-list">
+      {users.map(([ini, name, role, isOn]) => (
+        <div class={isOn ? 'op-row' : 'op-row is-off'}><span class="op-avatar">{ini}</span><span class="op-name">{name}</span><span class="op-role">{role}</span></div>
+      ))}
+    </div>
+  </div>
+)}
+
+{kind === 'tile' && (
+  <div class="sh-ex-grid is-one sh-root">
+    <div class="sh-ex op-ex">
+      <div class="op-tile is-off op-tile-lg" role="img" aria-label={L('A turned-off connection: the logo is faded, the text uses the disabled colour', 'Một kết nối đã tắt: logo mờ đi, chữ dùng màu disabled')}>
+        <span class="op-tile-top"><Pin solid label={`${L('Opacity', 'Độ mờ')}: opacity.disabled`} at="top" len="200"><span class="op-logo is-c">AC</span></Pin><span class="op-switch"></span></span>
+        <b>{L('Accounting', 'Kế toán')}</b>
+        <Pin solid label={`${L('Text', 'Chữ')}: color.text.disabled`} at="bottom" len="300"><span class="op-status">{off}</span></Pin>
+      </div>
+    </div>
+  </div>
+)}
+
+{kind === 'scrim' && (
+  <div class="el-themes sh-root">
+    {['light', 'dark'].map((mode) => (
+      <figure class={`el-theme bh-scope-${mode}`}>
+        <figcaption>{mode === 'light' ? L('Light: graphite at 40%', 'Light: graphite 40%') : L('Dark: black at 60%', 'Dark: đen 60%')}</figcaption>
+        <div class="op-scrim-box" role="img" aria-label={L('A dialog over the scrim', 'Dialog nằm trên lớp phủ mờ')}>
+          <div class="op-lines"><span style="width: 80%"></span><span style="width: 60%"></span><span style="width: 70%"></span></div>
+          <div class="op-scrim"></div>
+          <div class="op-dialog">Dialog</div>
+          <span class="op-scrim-pin"><Pin solid label={`${L('Background', 'Nền')}: color.surface.scrim`} at="bottom" len="200"><i class="el-dot"></i></Pin></span>
+        </div>
+      </figure>
+    ))}
+  </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">
+          {item === 'container' && (
+            <div class={side === 'do' ? 'op-tile is-off' : 'op-tile is-wrong'}><span class="op-tile-top"><span class="op-logo is-c">AC</span><span class="op-switch"></span></span><b>{L('Accounting', 'Kế toán')}</b><span class="op-status">{off}</span></div>
+          )}
+          {item === 'controls' && (
+            <div class="op-band"><span class="op-band-text">{L('Sync paused for 2 stores', 'Đã tạm dừng đồng bộ 2 cửa hàng')}</span><span class={side === 'do' ? 'sp-btn op-btn-off' : 'sp-btn is-primary op-btn-faded'}>{L('Resume', 'Tiếp tục')}</span></div>
+          )}
+        </div>
+        <p>
+          {item === 'container' && side === 'do' && L('Fade the logo only. The card keeps its border, and the text uses the disabled colour.', 'Chỉ làm mờ logo. Card giữ nguyên viền, chữ dùng màu disabled.')}
+          {item === 'container' && side === 'dont' && L('Don’t fade the whole card. Its border and text fade too, and the page shows through.', 'Không làm mờ cả card. Viền và chữ cũng mờ theo, và nền trang lộ ra phía sau.')}
+          {item === 'controls' && side === 'do' && L('Turn a control off with the disabled colours. It looks the same on any background.', 'Tắt một control bằng các màu disabled. Nó trông giống nhau trên mọi nền.')}
+          {item === 'controls' && side === 'dont' && L('Don’t fade a control with opacity. The background shows through, and the text loses contrast.', 'Không làm mờ control bằng opacity. Nền phía sau lộ ra và chữ mất độ tương phản.')}
+        </p>
+      </figure>
+    ))}
+  </div>
+)}

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

@@ -7,6 +7,7 @@ import { tokensByPrefix } from '../lib/tokens';
 import { tokenDescriptionsVi } from '../lib/token-descriptions-vi';
 import { langOf } from '../lib/i18n';
 import Pin from './ShapePin.astro';
+import CircleAlert from '@lucide/astro/icons/circle-alert';
 
 interface Props {
   kind: 'radius-scale' | 'radius-use' | 'nesting' | 'focus-radius' | 'border-scale' | 'border-use' | 'dodont';
@@ -85,7 +86,7 @@ const tick = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-
         <div class="sh-ex"><Pin label="radius.100" r="var(--bh-radius-100)"><span class="sp-btn is-primary">{L('Connect', 'Kết nối')}</span></Pin></div>
         <div class="sh-ex"><Pin label="radius.100" r="var(--bh-radius-100)"><span class="sp-input" style="width: 14rem"><span style="width: var(--bh-space-150)"></span><span>mystore.example.com</span></span></Pin></div>
         <div class="sh-ex"><Pin label="radius.100" r="var(--bh-radius-100)"><span class="sh-tip">{L('Copied to clipboard', 'Đã sao chép')}</span></Pin></div>
-        <div class="sh-ex"><Pin label="radius.100" r="var(--bh-radius-100)"><span class="sh-alert"><b>{L('Sync failed for 12 orders', 'Đồng bộ lỗi 12 đơn hàng')}</b><span>{L('Retrying in 5 minutes.', 'Thử lại sau 5 phút.')}</span></span></Pin></div>
+        <div class="sh-ex"><Pin label="radius.100" r="var(--bh-radius-100)"><span class="kit-banner is-danger"><CircleAlert size={16} aria-hidden="true" />{L('Sync failed for 12 orders. Retrying in 5 minutes.', 'Đồng bộ lỗi 12 đơn hàng. Thử lại sau 5 phút.')}</span></Pin></div>
       </Fragment>
     )}
     {item === '150' && (
@@ -107,10 +108,10 @@ const tick = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-
     )}
     {item === 'full' && (
       <Fragment>
-        <div class="sh-ex"><Pin label="radius.full" r="calc(var(--bh-space-600) / 2)"><span class="sh-avatar">TN</span></Pin></div>
-        <div class="sh-ex"><Pin label="radius.full" r="calc(var(--bh-size-control-small) / 2)"><span class="sh-switch" role="img" aria-label={L('Switch, on', 'Switch, đang bật')}></span></Pin></div>
+        <div class="sh-ex"><Pin label="radius.full" r="calc(var(--bh-size-control-default) / 2)"><span class="sh-avatar">TN</span></Pin></div>
+        <div class="sh-ex"><Pin label="radius.full" r="calc(var(--bh-space-250) / 2)"><span class="sh-switch" role="img" aria-label={L('Switch, on', 'Switch, đang bật')}></span></Pin></div>
         <div class="sh-ex"><Pin label="radius.full" r="calc(var(--bh-size-control-default) / 2)"><span class="sh-chip">{L('Online store', 'Cửa hàng online')}<span aria-hidden="true">×</span></span></Pin></div>
-        <div class="sh-ex"><Pin label="radius.full" r="calc(var(--bh-size-control-small) / 2)"><span class="sh-tag is-pill">{L('Connected', 'Đã kết nối')}</span></Pin></div>
+        <div class="sh-ex"><Pin label="radius.full" r="calc(var(--bh-space-250) / 2)"><span class="sh-tag is-pill">{L('Connected', 'Đã kết nối')}</span></Pin></div>
       </Fragment>
     )}
   </div>
@@ -179,7 +180,7 @@ const tick = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-
     )}
     {item === 'accent' && (
       <Fragment>
-        <div class="sh-ex is-b is-span is-left"><Pin solid label="border.width.accent" at="left" wide><span class="sh-alert"><b>{L('Sync failed for 12 orders', 'Đồng bộ lỗi 12 đơn hàng')}</b><span>{L('The store returned 429. Retrying in 5 minutes.', 'Cửa hàng trả về 429. Thử lại sau 5 phút.')}</span></span></Pin></div>
+        <div class="sh-ex is-b is-span is-left"><Pin solid label="border.width.accent" at="left" wide><span class="sh-alert"><b>{L('Before the first sync', 'Trước lần đồng bộ đầu tiên')}</b><span>{L('Map the order fields. Fields without a mapping are skipped.', 'Hãy ánh xạ các trường đơn hàng. Trường chưa ánh xạ sẽ bị bỏ qua.')}</span></span></Pin></div>
         <div class="sh-ex is-b is-span is-left"><Pin solid label="border.width.accent" at="left"><p class="sh-quote">{L('Use one radius for every control.', 'Mọi control dùng chung một radius.')}</p></Pin></div>
         <div class="sh-ex is-b is-span is-left">
           <span class="sh-frame">
@@ -202,9 +203,9 @@ const tick = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-
       <div class="sp-dd-stage">
         {item === 'nested' && <div class="sh-outer" style="border-radius: var(--bh-radius-200); padding: var(--bh-space-100); width: 13rem"><span class="sh-inner" style="border-radius: var(--bh-radius-100); min-height: 4rem">{L('Button group', 'Nhóm nút')}</span></div>}
         {item === 'controls' && <span class="sh-row"><span class="sp-input" style="width: 11rem"><span style="width: var(--bh-space-150)"></span><span>{L('Search orders', 'Tìm đơn hàng')}</span></span><span class="sp-btn is-primary">{L('Search', 'Tìm')}</span></span>}
-        {item === 'corners' && <span class="sh-alert"><b>{L('Sync failed', 'Đồng bộ lỗi')}</b><span>{L('12 orders were not sent.', '12 đơn chưa được gửi.')}</span></span>}
+        {item === 'corners' && <span class="sh-alert"><b>{L('Before the first sync', 'Trước lần đồng bộ đầu tiên')}</b><span>{L('Map the order fields.', 'Hãy ánh xạ các trường đơn hàng.')}</span></span>}
         {item === 'selected' && <span class="sh-tabs"><span class="is-on">{L('Overview', 'Tổng quan')}</span><span>{L('Mappings', 'Mapping')}</span><span>{L('History', 'Lịch sử')}</span></span>}
-        {item === 'accent' && <span class="sh-alert"><b>{L('Sync failed', 'Đồng bộ lỗi')}</b><span>{L('12 orders were not sent.', '12 đơn chưa được gửi.')}</span></span>}
+        {item === 'accent' && <span class="sh-alert"><b>{L('Before the first sync', 'Trước lần đồng bộ đầu tiên')}</b><span>{L('Map the order fields.', 'Hãy ánh xạ các trường đơn hàng.')}</span></span>}
         {item === 'cards' && <span class="sh-card"><b>{L('Online store', 'Cửa hàng online')}</b><span>{L('Connected', 'Đã kết nối')}</span></span>}
       </div>
       <p>
@@ -221,9 +222,9 @@ const tick = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-
       <div class="sp-dd-stage">
         {item === 'nested' && <div class="sh-outer" style="border-radius: var(--bh-radius-200); padding: var(--bh-space-100); width: 13rem"><span class="sh-inner" style="border-radius: var(--bh-radius-200); min-height: 4rem">{L('Button group', 'Nhóm nút')}</span></div>}
         {item === 'controls' && <span class="sh-row"><span class="sp-input" style="width: 11rem; border-radius: var(--bh-radius-050)"><span style="width: var(--bh-space-150)"></span><span>{L('Search orders', 'Tìm đơn hàng')}</span></span><span class="sp-btn is-primary" style="border-radius: var(--bh-radius-full)">{L('Search', 'Tìm')}</span></span>}
-        {item === 'corners' && <span class="sh-alert is-squared"><b>{L('Sync failed', 'Đồng bộ lỗi')}</b><span>{L('12 orders were not sent.', '12 đơn chưa được gửi.')}</span></span>}
+        {item === 'corners' && <span class="sh-alert is-squared"><b>{L('Before the first sync', 'Trước lần đồng bộ đầu tiên')}</b><span>{L('Map the order fields.', 'Hãy ánh xạ các trường đơn hàng.')}</span></span>}
         {item === 'selected' && <span class="sh-tabs" style="--sh-sel: var(--bh-border-width-accent)"><span class="is-on">{L('Overview', 'Tổng quan')}</span><span>{L('Mappings', 'Mapping')}</span><span>{L('History', 'Lịch sử')}</span></span>}
-        {item === 'accent' && <span class="sh-alert is-boxed"><b>{L('Sync failed', 'Đồng bộ lỗi')}</b><span>{L('12 orders were not sent.', '12 đơn chưa được gửi.')}</span></span>}
+        {item === 'accent' && <span class="sh-alert is-boxed"><b>{L('Before the first sync', 'Trước lần đồng bộ đầu tiên')}</b><span>{L('Map the order fields.', 'Hãy ánh xạ các trường đơn hàng.')}</span></span>}
         {item === 'cards' && <span class="sh-card" style="border-width: var(--bh-border-width-selected); border-color: var(--bh-color-border-bold)"><b>{L('Online store', 'Cửa hàng online')}</b><span>{L('Connected', 'Đã kết nối')}</span></span>}
       </div>
       <p>
@@ -231,7 +232,7 @@ const tick = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-
         {item === 'controls' && L('A 4 px input next to a pill button. The row looks like two different products.', 'Ô nhập 4 px cạnh nút viên thuốc. Hàng control trông như của hai sản phẩm khác nhau.')}
         {item === 'corners' && L('Square only the left corners. One box ends up with two radii.', 'Chỉ làm vuông hai góc trái. Một hộp có hai radius khác nhau.')}
         {item === 'selected' && L('Use the 4 px accent for a selected tab. Accent is for status and emphasis.', 'Dùng accent 4 px cho tab đang chọn. Accent dành cho trạng thái và nhấn mạnh.')}
-        {item === 'accent' && L('Draw 4 px all the way round. The alert shouts and the message gets lost.', 'Vẽ 4 px quanh cả hộp. Alert quá nặng và nội dung bị lấn át.')}
+        {item === 'accent' && L('Draw 4 px all the way round. The box shouts and the message gets lost.', 'Vẽ 4 px quanh cả hộp. Hộp trông quá nặng và nội dung bị lấn át.')}
         {item === 'cards' && L('Give every card a 2 px border. Nothing can show selection any more.', 'Card nào cũng viền 2 px. Không còn cách nào để báo trạng thái đang chọn.')}
       </p>
     </figure>

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

@@ -5,7 +5,9 @@
 interface Props {
   label: string;
   /** corner: the bottom-left corner. bottom / top: the middle of the bottom or top edge. left: the middle of the left edge. */
-  at?: 'corner' | 'bottom' | 'top' | 'left';
+  at?: 'corner' | 'bottom' | 'top' | 'left' | 'inside' | 'inside-left';
+  /** inside / inside-left: how far in from the left edge the dot sits, as a space token step. Use these to point at a fill (a surface colour), not an edge. */
+  inset?: string;
   /** The element's radius, e.g. var(--bh-radius-100). Draws the curve inside the hexagon. Leave out for border pins. */
   r?: string;
   /** Line length as a space token step, e.g. '300' for space.300. */
@@ -17,6 +19,6 @@ interface Props {
   /** Line length when a left pin drops down on narrow screens. */
   lenNarrow?: string;
 }
-const { label, at = 'corner', r, len = '300', wide = false, solid = false, lenNarrow } = Astro.props;
+const { label, at = 'corner', r, len = '300', wide = false, solid = false, lenNarrow, inset = '200' } = Astro.props;
 ---
-<span class:list={['sh-pin', { 'is-wide': wide }]}><slot /><span class:list={['sh-anno', `is-${at}`, { 'is-solid': solid }]} style={`--sh-len: var(--bh-space-${len});${lenNarrow ? ` --sh-len-n: var(--bh-space-${lenNarrow});` : ''}${r ? ` --sh-r: ${r};` : ''}`} aria-hidden="true"><i class="sh-mark">{r && <b class="sh-arc"></b>}</i><b class="sh-ln"></b><code>{label}</code></span></span>
+<span class:list={['sh-pin', { 'is-wide': wide }]}><slot /><span class:list={['sh-anno', `is-${at}`, { 'is-solid': solid }]} style={`--sh-len: var(--bh-space-${len}); --sh-in: var(--bh-space-${inset});${lenNarrow ? ` --sh-len-n: var(--bh-space-${lenNarrow});` : ''}${r ? ` --sh-r: ${r};` : ''}`} aria-hidden="true"><i class="sh-mark">{r && <b class="sh-arc"></b>}</i><b class="sh-ln"></b><code>{label}</code></span></span>