@beehexa/design-rules 0.0.0-stage → 2611.3.2

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

@@ -0,0 +1,211 @@
+---
+import { areaOf, sectionOf, siteAreas } from '../lib/navigation';
+import { basePath, langOf, localize, t, viPublic } from '../lib/i18n';
+
+// Header logo: "beehexa design", PNG drawn at 3× and shrunk by the browser to a 24 px icon
+// (28 px image: 2 px above and below the icon, so the icon is its centre; the "g" of "design"
+// hangs into the bottom 2 px). Shrinking a larger picture
+// softens the edges a little, which hides the stair steps of the 30° edges on 100% scale
+// screens. One image per tone (light, dark); chrome.css shows the one for the page theme. At 188 px wide it fits next to the section links at every width, so there is no
+// shorter version. Never crop the image to the ink: the "g" then loses its bottom row.
+const png = (kind: string, tone: string) => `/brand/logos/ui/png/${kind}-${tone}@3x.png`;
+const tones = ['light', 'dark'] as const;
+import '../styles/chrome.css';
+// Icons: Lucide (decision 26). 16 px next to 14 px text, 20 px in the header toolbar.
+import SearchIcon from '@lucide/astro/icons/search';
+import Moon from '@lucide/astro/icons/moon';
+import Sun from '@lucide/astro/icons/sun';
+import Menu from '@lucide/astro/icons/menu';
+
+const lang = langOf(Astro.url.pathname);
+const T = t(lang);
+const base = basePath(Astro.url.pathname);
+const current = areaOf(sectionOf(base));
+const areaLabel = (id: string) => (id === 'news' ? T.news : T.designSystem);
+// The same page in the other language.
+const otherLang = lang === 'vi' ? 'en' : 'vi';
+const otherHref = localize(base, otherLang);
+---
+
+<header class="site-header">
+  <div class="header-inner">
+    <a class="header-brand" href={localize('/get-started/', lang)} aria-label={`beehexa design – ${T.home}`}>
+      {tones.map((t) => <img class:list={['header-logo-img', `logo-${t}`]} src={png('beehexa-design', t)} alt="" height="28" />)}
+    </a>
+
+    <nav class="header-nav" aria-label="Site">
+      {siteAreas.map((area) => (
+        <a href={localize(area.href, lang)} aria-current={area.id === current ? 'page' : undefined}>{areaLabel(area.id)}</a>
+      ))}
+    </nav>
+
+    <div class="header-tools">
+      <div class="search" data-search>
+        <SearchIcon size={16} class="search-icon" />
+        <input
+          type="search"
+          placeholder={T.search}
+          aria-label={T.searchLabel}
+          role="combobox"
+          aria-expanded="false"
+          aria-controls="search-results"
+          aria-autocomplete="list"
+          autocomplete="off"
+          data-search-input
+        />
+        <kbd class="search-hint" aria-hidden="true">Ctrl K</kbd>
+        <ul data-empty={T.searchEmpty} class="search-results" id="search-results" role="listbox" aria-label={T.search} hidden data-search-results></ul>
+      </div>
+      <button class="icon-button search-open" type="button" aria-label={T.search} data-search-open>
+        <SearchIcon size={20} />
+      </button>
+      {viPublic && <a class="icon-button lang-switch" href={otherHref} hreflang={otherLang} lang={otherLang} aria-label={T.otherLang} title={T.otherLang}>{T.otherLangShort}</a>}
+      <button class="icon-button" type="button" aria-label={T.themeDark} data-theme-toggle data-label-dark={T.themeDark} data-label-light={T.themeLight}>
+        <Moon size={20} class="theme-moon" />
+        <Sun size={20} class="theme-sun" />
+      </button>
+      <details class="header-menu">
+        <summary class="icon-button" aria-label={T.menu}>
+          <Menu size={20} />
+        </summary>
+        <nav aria-label="Site">
+          {siteAreas.map((area) => (
+            <a href={localize(area.href, lang)} aria-current={area.id === current ? 'page' : undefined}>{areaLabel(area.id)}</a>
+          ))}
+          {viPublic && <a class="menu-lang" href={otherHref} hreflang={otherLang} lang={otherLang}>{T.otherLang}</a>}
+        </nav>
+      </details>
+    </div>
+  </div>
+</header>
+
+<script>
+  type Page = { title: string; section: string; description: string; href: string };
+
+  const root = document.querySelector<HTMLElement>('[data-search]')!;
+  const input = root.querySelector<HTMLInputElement>('[data-search-input]')!;
+  const list = root.querySelector<HTMLUListElement>('[data-search-results]')!;
+  let pages: Page[] | undefined;
+  let results: Page[] = [];
+  let active = -1;
+
+  async function load() {
+    if (pages) return pages;
+    const response = await fetch('/search.json');
+    pages = (await response.json()) as Page[];
+    return pages;
+  }
+
+  function score(page: Page, words: string[]) {
+    const title = page.title.toLowerCase();
+    const text = `${title} ${page.section} ${page.description}`.toLowerCase();
+    if (!words.every((word) => text.includes(word))) return 0;
+    return words.reduce((sum, word) => sum + (title.startsWith(word) ? 4 : title.includes(word) ? 2 : 1), 0);
+  }
+
+  function render() {
+    list.replaceChildren();
+    if (!input.value.trim()) {
+      list.hidden = true;
+      input.setAttribute('aria-expanded', 'false');
+      return;
+    }
+    if (results.length === 0) {
+      const empty = document.createElement('li');
+      empty.className = 'search-empty';
+      empty.textContent = list.dataset.empty ?? '';
+      list.append(empty);
+    }
+    results.forEach((page, index) => {
+      const item = document.createElement('li');
+      item.id = `search-result-${index}`;
+      item.setAttribute('role', 'option');
+      item.setAttribute('aria-selected', String(index === active));
+      const link = document.createElement('a');
+      link.href = document.documentElement.lang === 'vi' ? `/vi${page.href}` : page.href;
+      link.tabIndex = -1;
+      const title = document.createElement('b');
+      title.textContent = page.title;
+      const meta = document.createElement('span');
+      meta.textContent = page.section;
+      link.append(title, meta);
+      item.append(link);
+      list.append(item);
+    });
+    list.hidden = false;
+    input.setAttribute('aria-expanded', 'true');
+    input.setAttribute('aria-activedescendant', active >= 0 ? `search-result-${active}` : '');
+  }
+
+  input.addEventListener('focus', () => void load());
+  input.addEventListener('input', async () => {
+    const words = input.value.toLowerCase().split(/\s+/).filter(Boolean);
+    const all = await load();
+    results = all
+      .map((page) => ({ page, s: score(page, words) }))
+      .filter((row) => row.s > 0)
+      .sort((a, b) => b.s - a.s)
+      .slice(0, 8)
+      .map((row) => row.page);
+    active = results.length ? 0 : -1;
+    render();
+  });
+  input.addEventListener('keydown', (event) => {
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      if (!results.length) return;
+      active = (active + (event.key === 'ArrowDown' ? 1 : -1) + results.length) % results.length;
+      render();
+    } else if (event.key === 'Enter' && results[active]) {
+      event.preventDefault();
+      location.href = document.documentElement.lang === 'vi' ? `/vi${results[active].href}` : results[active].href;
+    } else if (event.key === 'Escape') {
+      input.value = '';
+      results = [];
+      render();
+      document.body.removeAttribute('data-search-open');
+      input.blur();
+    }
+  });
+  document.addEventListener('click', (event) => {
+    if (!root.contains(event.target as Node)) {
+      list.hidden = true;
+      input.setAttribute('aria-expanded', 'false');
+    }
+  });
+  document.addEventListener('keydown', (event) => {
+    if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'k') {
+      event.preventDefault();
+      document.body.setAttribute('data-search-open', '');
+      input.focus();
+    }
+  });
+  document.querySelector('[data-search-open]')?.addEventListener('click', () => {
+    document.body.setAttribute('data-search-open', '');
+    input.focus();
+  });
+  input.addEventListener('blur', () => {
+    setTimeout(() => {
+      if (!root.contains(document.activeElement)) document.body.removeAttribute('data-search-open');
+    }, 150);
+  });
+
+  const isMac = /Mac|iPhone|iPad/.test(navigator.platform);
+  if (isMac) root.querySelector('.search-hint')!.textContent = '⌘ K';
+
+  const toggle = document.querySelector<HTMLButtonElement>('[data-theme-toggle]');
+  const sync = () => {
+    const dark = document.documentElement.dataset.theme === 'dark';
+    toggle?.setAttribute('aria-label', (dark ? toggle!.dataset.labelLight : toggle!.dataset.labelDark) ?? '');
+    document.querySelector('meta[name="theme-color"]')?.setAttribute('content', getComputedStyle(document.documentElement).getPropertyValue('--bh-color-surface-page').trim() || (dark ? '#181717' : '#ffffff'));
+  };
+  sync();
+  toggle?.addEventListener('click', () => {
+    const next = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
+    document.documentElement.dataset.theme = next;
+    try {
+      localStorage.setItem('bh-theme', next);
+    } catch {}
+    sync();
+  });
+</script>

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

@@ -0,0 +1,172 @@
+---
+// Illustrations for the Spacing page. Sizes come from tokens/spacing.json through the CSS
+// variables, so every bar and gap on the page is the real value.
+import '../styles/layout.css';
+import { tokensByPrefix } from '../lib/tokens';
+import { tokenDescriptionsVi } from '../lib/token-descriptions-vi';
+import { langOf } from '../lib/i18n';
+
+interface Props {
+  kind: 'scale' | 'anatomy' | 'padding-gap' | 'dodont';
+  /** For kind="dodont": which pair to show. */
+  item?: 'scale' | 'grouping' | 'nudge';
+}
+const { kind, item } = Astro.props;
+const vi = langOf(Astro.url.pathname) === 'vi';
+const L = (en: string, viText: string) => (vi ? viText : en);
+
+// Rem to px at the default 16 px root size.
+const toPx = (value: string) => (value.endsWith('rem') ? parseFloat(value) * 16 : parseFloat(value) || 0);
+const scale = tokensByPrefix('space')
+  .map((t) => ({ ...t, px: toPx(t.resolved), use: (vi ? tokenDescriptionsVi[t.name] ?? t.description : t.description).replace(/^\d+( px)?\. /, '') }))
+  .sort((a, b) => a.px - b.px);
+
+const store = '<svg class="sp-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 9l1.5-5h15L21 9"/><path d="M4 9v11h16V9"/><path d="M3 9h18"/><path d="M9 20v-6h6v6"/></svg>';
+const bell = '<svg class="sp-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9"/><path d="M10.3 21a1.94 1.94 0 0 0 3.4 0"/></svg>';
+---
+
+{kind === 'scale' && (
+  <ul class="sp-scale sp-root" aria-label={L('Spacing scale', 'Thang khoảng cách')}>
+    {scale.map((t) => (
+      <li>
+        <span class="sp-name"><code>{t.name}</code><span class="sp-var">{t.cssVar}</span></span>
+        <span class="sp-px">{t.px} px<small>{t.resolved}</small></span>
+        <span class="sp-bar-cell" aria-hidden="true">
+          <span class:list={['sp-bar', { 'is-zero': t.px === 0, 'is-hairline': t.px > 0 && t.px < 4 }]} style={t.px === 0 ? undefined : `width: var(${t.cssVar})`}></span>
+        </span>
+        <span class="sp-use">{t.use}</span>
+      </li>
+    ))}
+  </ul>
+)}
+
+{kind === 'anatomy' && (
+  <figure class="sp-figure sp-root">
+    <div class="sp-stage">
+      <div class="sp-card" role="img" aria-label={L('A card for connecting an online store, with each space marked: 24 px card padding, 4 px between the icon and the title and between the title and the description, 20 px under the heading, 8 px between each label and its field, 12 px inside the field, 16 px between fields, 32 px before the buttons and 8 px between them.', 'Card kết nối cửa hàng online, có đánh dấu từng khoảng: padding card 24 px, 4 px giữa icon và tiêu đề và giữa tiêu đề và mô tả, 20 px dưới tiêu đề, 8 px giữa nhãn và ô nhập, 12 px bên trong ô nhập, 16 px giữa các ô nhập, 32 px trước các nút và 8 px giữa hai nút.')}>
+        <div class="sp-card-pad sp-stack">
+          <span class="sp-tag">24</span>
+          <div class="sp-row">
+            <Fragment set:html={store} />
+            <span class="sp-gap is-h" style="width: var(--bh-space-050)"><span class="sp-tag">4</span></span>
+            <span class="sp-title">{L('Online store', 'Cửa hàng online')}</span>
+          </div>
+          <span class="sp-gap is-v" style="height: var(--bh-space-050)"><span class="sp-tag">4</span></span>
+          <span class="sp-desc">{L('Connect the store to sync orders and stock.', 'Kết nối cửa hàng để đồng bộ đơn hàng và tồn kho.')}</span>
+          <span class="sp-gap is-v" style="height: var(--bh-space-250)"><span class="sp-tag">20</span></span>
+          <span class="sp-label">{L('Store URL', 'URL cửa hàng')}</span>
+          <span class="sp-gap is-v" style="height: var(--bh-space-100)"><span class="sp-tag">8</span></span>
+          <span class="sp-input">
+            <span class="sp-gap is-h" style="width: var(--bh-space-150)"><span class="sp-tag is-below">12</span></span>
+            <span>mystore.example.com</span>
+          </span>
+          <span class="sp-gap is-v" style="height: var(--bh-space-200)"><span class="sp-tag">16</span></span>
+          <span class="sp-label">{L('API key', 'API key')}</span>
+          <span class="sp-gap is-v" style="height: var(--bh-space-100)"><span class="sp-tag">8</span></span>
+          <span class="sp-input">
+            <span class="sp-gap is-h" style="width: var(--bh-space-150)"></span>
+            <span>{L('Paste the key from the store', 'Dán key lấy từ cửa hàng')}</span>
+          </span>
+          <span class="sp-gap is-v" style="height: var(--bh-space-400)"><span class="sp-tag">32</span></span>
+          <div class="sp-row is-end">
+            <span class="sp-btn">{L('Cancel', 'Huỷ')}</span>
+            <span class="sp-gap is-h" style="width: var(--bh-space-100)"><span class="sp-tag">8</span></span>
+            <span class="sp-btn is-primary">{L('Connect', 'Kết nối')}</span>
+          </div>
+        </div>
+      </div>
+    </div>
+    <figcaption><span class="sp-legend"><span class="sp-swatch" aria-hidden="true"></span> {L('Tinted areas are space, marked in px. Small steps hold things that belong together; large steps separate groups.', 'Vùng tô màu là khoảng trống, ghi bằng px. Bậc nhỏ giữ các thứ thuộc về nhau ở gần nhau; bậc lớn tách các nhóm.')}</span></figcaption>
+  </figure>
+)}
+
+{kind === 'padding-gap' && (
+  <div class="sp-pair sp-root">
+    <figure>
+      <div class="sp-pair-stage"><span class="sp-padbox">{L('Card content', 'Nội dung card')}</span></div>
+      <figcaption><b>Padding</b><span>{L('Space inside an element, between its edge and its content. Set on the element.', 'Khoảng trống bên trong một phần tử, giữa mép và nội dung của nó. Đặt trên chính phần tử đó.')}</span></figcaption>
+    </figure>
+    <figure>
+      <div class="sp-pair-stage">
+        <span class="sp-row">
+          <span class="sp-chip">{L('Orders', 'Đơn hàng')}</span>
+          <span class="sp-gap is-h" style="width: var(--bh-space-100)"></span>
+          <span class="sp-chip">{L('Products', 'Sản phẩm')}</span>
+          <span class="sp-gap is-h" style="width: var(--bh-space-100)"></span>
+          <span class="sp-chip">{L('Stock', 'Tồn kho')}</span>
+        </span>
+      </div>
+      <figcaption><b>Gap</b><span>{vi ? <Fragment>Khoảng trống giữa các phần tử. Đặt trên phần tử cha bằng <code>gap</code>, không dùng margin trên phần tử con.</Fragment> : <Fragment>Space between elements. Set on their parent with <code>gap</code>, never as margins on the children.</Fragment>}</span></figcaption>
+    </figure>
+  </div>
+)}
+
+{kind === 'dodont' && (
+  <div class="sp-dd sp-root">
+    <figure class="sp-dd-panel is-do">
+      <figcaption><span aria-hidden="true">✓</span> {L('Do', 'Nên')}</figcaption>
+      <div class="sp-dd-stage">
+        {item === 'scale' && (<code>gap: var(--bh-space-200);<br />padding: var(--bh-space-300);</code>)}
+        {item === 'grouping' && (
+          <div class="sp-mini" role="img" aria-label={L('Two groups of fields: each label sits 8 px above its field, fields are 16 px apart and the groups 32 px apart.', 'Hai nhóm ô nhập: nhãn cách ô của nó 8 px, các ô cách nhau 16 px và các nhóm cách nhau 32 px.')}>
+            <span class="sp-mini-group">{L('Store', 'Cửa hàng')}</span>
+            <span style="height: var(--bh-space-100)"></span>
+            <span class="sp-label">{L('Store URL', 'URL cửa hàng')}</span>
+            <span style="height: var(--bh-space-100)"></span>
+            <span class="sp-input"><span style="width: var(--bh-space-150)"></span><span>mystore.example.com</span></span>
+            <span style="height: var(--bh-space-400)"></span>
+            <span class="sp-mini-group">{L('Sync', 'Đồng bộ')}</span>
+            <span style="height: var(--bh-space-100)"></span>
+            <span class="sp-label">{L('Every', 'Mỗi')}</span>
+            <span style="height: var(--bh-space-100)"></span>
+            <span class="sp-input"><span style="width: var(--bh-space-150)"></span><span>{L('15 minutes', '15 phút')}</span></span>
+          </div>
+        )}
+        {item === 'nudge' && (
+          <span class="sp-dd-row" style="gap: var(--bh-space-100)">
+            <span class="sp-badge-host" role="img" aria-label={L('Bell icon with a red dot 2 px from its corner', 'Icon chuông với chấm đỏ cách góc 2 px')}><Fragment set:html={bell} /><span class="sp-badge"></span></span>
+            <span class="sp-btn">{L('Cancel', 'Huỷ')}</span>
+            <span class="sp-btn is-primary">{L('Save', 'Lưu')}</span>
+          </span>
+        )}
+      </div>
+      <p>
+        {item === 'scale' && L('Use a spacing token for every padding, gap and margin.', 'Dùng token khoảng cách cho mọi padding, gap và margin.')}
+        {item === 'grouping' && L('Put a label closer to its own field than to anything else, and groups further apart than fields.', 'Đặt nhãn gần ô của nó hơn mọi thứ khác, và các nhóm cách xa nhau hơn các ô.')}
+        {item === 'nudge' && L('Use 2 px only to nudge a badge or a dot. Buttons stay 8 px apart.', 'Chỉ dùng 2 px để xê dịch badge hoặc chấm. Các nút vẫn cách nhau 8 px.')}
+      </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="sp-dd-stage">
+        {item === 'scale' && (<code>gap: 18px;<br />padding: 13px 22px;</code>)}
+        {item === 'grouping' && (
+          <div class="sp-mini" role="img" aria-label={L('The same fields with 16 px everywhere: labels float halfway between two fields and the groups run together.', 'Cùng các ô đó nhưng chỗ nào cũng 16 px: nhãn lơ lửng giữa hai ô và các nhóm dính vào nhau.')}>
+            <span class="sp-mini-group">{L('Store', 'Cửa hàng')}</span>
+            <span style="height: var(--bh-space-200)"></span>
+            <span class="sp-label">{L('Store URL', 'URL cửa hàng')}</span>
+            <span style="height: var(--bh-space-200)"></span>
+            <span class="sp-input"><span style="width: var(--bh-space-150)"></span><span>mystore.example.com</span></span>
+            <span style="height: var(--bh-space-200)"></span>
+            <span class="sp-mini-group">{L('Sync', 'Đồng bộ')}</span>
+            <span style="height: var(--bh-space-200)"></span>
+            <span class="sp-label">{L('Every', 'Mỗi')}</span>
+            <span style="height: var(--bh-space-200)"></span>
+            <span class="sp-input"><span style="width: var(--bh-space-150)"></span><span>{L('15 minutes', '15 phút')}</span></span>
+          </div>
+        )}
+        {item === 'nudge' && (
+          <span class="sp-dd-row" style="gap: var(--bh-space-025)">
+            <span class="sp-btn">{L('Cancel', 'Huỷ')}</span>
+            <span class="sp-btn is-primary">{L('Save', 'Lưu')}</span>
+          </span>
+        )}
+      </div>
+      <p>
+        {item === 'scale' && L('Pixel values off the scale. Nothing lines up, and each screen drifts a little further.', 'Giá trị pixel ngoài thang. Không gì thẳng hàng, và mỗi màn hình lại lệch thêm một chút.')}
+        {item === 'grouping' && L('The same space everywhere. Readers cannot tell which label belongs to which field.', 'Chỗ nào cũng cùng một khoảng. Người đọc không biết nhãn nào thuộc ô nào.')}
+        {item === 'nudge' && L('Controls 2 px apart. They read as one control and are easy to tap by mistake.', 'Các control cách nhau 2 px. Trông như một control và dễ bấm nhầm.')}
+      </p>
+    </figure>
+  </div>
+)}

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

@@ -0,0 +1,22 @@
+---
+import { releasePhaseLabels, type ReleasePhase } from '../lib/release-phases';
+
+interface Props {
+  status: ReleasePhase;
+  // Set to false inside another link, such as a sidebar item or a card.
+  link?: boolean;
+  // Default (20 px) in lists, the sidebar and running text; large (24 px) once per page, next to the title.
+  size?: 'default' | 'large';
+}
+
+const { status, link = true, size = 'default' } = Astro.props;
+const Tag = link ? 'a' : 'span';
+---
+
+<Tag
+  class:list={['status-badge', `status-${status}`, { 'is-large': size === 'large' }]}
+  href={link ? '/release-phases/' : undefined}
+  title={link ? 'About release phases' : undefined}
+>
+  {releasePhaseLabels[status]}
+</Tag>

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

@@ -0,0 +1,29 @@
+---
+import { getCollection } from 'astro:content';
+
+// What is in the system, with live page counts.
+const docs = await getCollection('docs');
+const count = (section: string) => docs.filter((entry) => entry.id.startsWith(`${section}/`)).length;
+const components = (await getCollection('components')).length;
+const news = (await getCollection('news')).length;
+const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+const areas = [
+  { title: 'Foundations', href: '/foundations/', text: 'Tokens, guidelines and styles such as color, type and logos.', meta: plural(count('foundations'), 'page') },
+  { title: 'Components', href: '/components/', text: 'Building blocks with usage, code and accessibility notes.', meta: plural(components, 'component') },
+  { title: 'Tools', href: '/tools/', text: 'Lint rules, the Ant Design Vue theme and docs for AI agents.', meta: plural(count('tools'), 'tool') },
+  { title: 'News', href: '/news/', text: 'Changes to the system, newest first.', meta: plural(news, 'post') },
+];
+---
+
+<ul class="card-grid area-grid">
+  {areas.map((area) => (
+    <li>
+      <a class="card" href={area.href}>
+        {area.title}
+        <p>{area.text}</p>
+        <span class="card-meta">{area.meta}</span>
+      </a>
+    </li>
+  ))}
+</ul>

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

@@ -0,0 +1,47 @@
+---
+import type { MarkdownHeading } from 'astro';
+import { langOf, t } from '../lib/i18n';
+import ChevronDown from '@lucide/astro/icons/chevron-down';
+
+interface Props {
+  headings: MarkdownHeading[];
+  // "aside" is the right-hand column; "menu" is the folded list on small screens.
+  variant?: 'aside' | 'menu';
+}
+
+const { variant = 'aside' } = Astro.props;
+const T = t(langOf(Astro.url.pathname));
+const headings = Astro.props.headings.filter((heading) => heading.depth === 2 || heading.depth === 3);
+---
+
+{headings.length > 1 && variant === 'aside' && (
+  <nav class="toc" aria-labelledby="toc-title">
+    <p class="toc-title" id="toc-title">{T.onThisPage}</p>
+    <ul>
+      {headings.map((heading) => (
+        <li class={`toc-depth-${heading.depth}`}><a href={`#${heading.slug}`} data-toc-link>{heading.text}</a></li>
+      ))}
+    </ul>
+  </nav>
+)}
+{headings.length > 1 && variant === 'menu' && (
+  <details class="toc-menu">
+    <summary>{T.onThisPage}<ChevronDown size={16} class="toc-menu-chevron" /></summary>
+    <nav aria-label={T.onThisPage}>
+    <ul>
+      {headings.map((heading) => (
+        <li class={`toc-depth-${heading.depth}`}><a href={`#${heading.slug}`} data-toc-link>{heading.text}</a></li>
+      ))}
+    </ul>
+    </nav>
+  </details>
+)}
+
+<style>
+  /* The folded list's chevron: a 16 px Lucide icon next to the 14 px label, 4 px apart. */
+  .toc-menu summary { display: flex; align-items: center; gap: var(--bh-space-050); }
+  .toc-menu summary::after { content: none; }
+  .toc-menu :global(.toc-menu-chevron) { flex: none; transition: transform 150ms ease; }
+  .toc-menu[open] :global(.toc-menu-chevron) { transform: rotate(180deg); }
+  @media (prefers-reduced-motion: reduce) { .toc-menu :global(.toc-menu-chevron) { transition: none; } }
+</style>

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

@@ -0,0 +1,40 @@
+---
+import { tokensByPrefix } from '../lib/tokens';
+import { tokenDescriptionsVi } from '../lib/token-descriptions-vi';
+import { langOf } from '../lib/i18n';
+
+// Lists every token whose name starts with `prefix`, read from tokens/*.json.
+interface Props {
+  prefix: string;
+}
+
+const tokens = tokensByPrefix(Astro.props.prefix);
+const vi = langOf(Astro.url.pathname) === 'vi';
+const L = (en: string, viText: string) => (vi ? viText : en);
+const describe = (name: string, en: string) => (vi ? tokenDescriptionsVi[name] ?? en : en);
+---
+
+<div class="table-wrap">
+  <table class="token-table">
+    <thead>
+      <tr><th scope="col">Token</th><th scope="col">{L('Value', 'Giá trị')}</th><th scope="col">{L('Description', 'Mô tả')}</th></tr>
+    </thead>
+    <tbody>
+      {tokens.map((token) => (
+        <tr>
+          <td><code>{token.cssVar}</code></td>
+          <td>
+            <span class="token-value">
+              {token.type === 'color' && <span class="swatch" style={`background: var(${token.cssVar})`} aria-hidden="true"></span>}
+              <code>{token.value}</code>
+            </span>
+            {token.value !== token.resolved && <span class="token-resolved">{token.resolved}</span>}
+            {token.darkResolved && <span class="token-resolved">{L('Dark', 'Tối')}: {token.dark && token.dark !== token.darkResolved ? `${token.dark} → ` : ''}{token.darkResolved}</span>}
+            {token.viResolved && <span class="token-resolved">{L('Vietnamese', 'Tiếng Việt')} (<code>lang="vi"</code>): {token.viResolved}</span>}
+          </td>
+          <td>{describe(token.name, token.description)}</td>
+        </tr>
+      ))}
+    </tbody>
+  </table>
+</div>