@keyfunc/keybricks-ds 2.3.1 → 2.4.0

package/DEPLOY.md

@@ -55,11 +55,11 @@ deploys the documentation site. Watch it under *Build → Pipelines*.
 **5. Cut the first release.**
 
 ```bash
-git tag v2.3.1 && git push --tags
+git tag v2.4.0 && git push --tags
 ```
 
 That tag runs `generated:check` → `version:check` → `npm publish`. Confirm under *Deploy →
-Package Registry*: `@keyfunc/keybricks-ds` 2.3.1.
+Package Registry*: `@keyfunc/keybricks-ds` 2.4.0.
 
 **6. Hand developers two things:** the Pages URL, and the `.npmrc` snippet in §4 below.
 
@@ -112,7 +112,7 @@ import tokens from '@keyfunc/keybricks-ds/tokens.json'                 // cross-
 ```
 
 Deep imports are the better default in Vue and in any app that cares about tree-shaking —
-a barrel of 122 exports asks the bundler to prove each one is unused.
+a barrel of 129 exports asks the bundler to prove each one is unused.
 
 ## 3. Publishing (maintainers)
 
@@ -130,6 +130,12 @@ git push && git push --tags
 `.gitlab-ci.yml` then runs: `generated:check` → `version:check` (tag must equal
 `package.json` version) → `npm publish` → `pages`.
 
+**Changelog.** Every release gets an entry at the top of `changelog.js` (version, ISO date, and
+items tagged `new` / `improved` / `fixed` / `breaking` / `removed`, each in English, Chinese and
+Japanese). The documentation site renders it as the *Changelog* section under Overview. While a
+version is still being built its entry carries `status: "unreleased"`; on release, drop the status
+and set the date. Migration details stay in `INTEGRATION.md`; the changelog is the short summary.
+
 **Versioning policy.** A token's *value* changing is a minor; a token being *renamed or
 removed* is a major, because consumer code references `var(--name)` directly. Adding a
 component or a prop is a minor. Changing a component's default appearance is a major —
@@ -156,7 +162,7 @@ GitLab injects `CI_JOB_TOKEN` — use that instead and no secret is stored anywh
 **Install — straight from git** (no registry, no publish; works today)
 
 ```json
-"@keyfunc/keybricks-ds": "git+ssh://git@gitlab.epm2demo.cn/Felix/keybricks-ds.git#v2.3.1"
+"@keyfunc/keybricks-ds": "git+ssh://git@gitlab.epm2demo.cn/Felix/keybricks-ds.git#v2.4.0"
 ```
 
 Because the package has no build step, a git dependency needs no `prepare` script — npm

package/DESIGN.md

@@ -138,6 +138,48 @@ and menu row is the tier's control text; a `Badge` or `Tag` is its own small obj
 exception. In content, a secondary annotation (a timestamp beside a name, a count beside a label)
 may be `--text-xs`. Never put a 14px label and a 12px control on the same baseline.
 
+### Count badges on tabs and segments
+
+A `Tabs`, `PanelTabs` or `PillTabs` tab, or a `SegmentedControl` option, may carry `count` (`{ label: "Submission", count: 3 }`).
+It renders 6px right of the label as a small full-radius badge: `--count-h` tall (sm 16 · md 18 · lg 20),
+6px sides, **12px tabular figures in the UI font** (digits are Latin, so the size is not bumped in CJK).
+The fill is the alpha wash `--neutral-alpha-8` — it darkens whatever it sits on by the same step, so the
+badge reads on a white tab, on the #f5f5f5 active pill and in dark mode alike (a solid `--bg-hover` vanished on
+the active pill). Selected is told from unselected by the text alone: `--text-heading` vs `--text-body` —
+never `--text-secondary`, which fails 4.5:1 on a grey fill at 12px. Under the blue active underline tab the
+badge stays neutral, so the blue is only the tab's own label and line. A count of 0 or none draws nothing; `showZero` (on the control, or per option) draws a muted
+0 so a filter set keeps its shape. The selected value is still matched by label — a count is decoration,
+never identity. Counts never appear in `iconOnly` segments.
+
+### App chrome
+
+The shell is `Sidebar` + optional `SidePanel` + `TopBar`, all 56px at the top edge. The rail is 240px (64px
+collapsed), with a 56px brand head without a rule, a 2px-gap list of 36px items and a pinned footer
+(Management, Knowledge Base) above a version line. Items that open a panel (`trailing: true`) carry a
+14px chevron; while a panel is open the rail collapses to its 64px icon form and the panel docks beside
+it at 240px, in the **same tone**. Tones: `recessed` (default — grey rail, the active item is a white tile
+with a hairline ring), `flush` (white rail), `contrast` (rail scoped to the dark theme) and `custom`
+(dark scope on one of ten `SIDEBAR_COLORS`). Pick one tone per product and pass it to both
+`Sidebar` and `SidePanel`. The top bar holds the bare search on the left and, on the right, the dark
+AI Assistant button, notifications, help and the user trigger, which opens `UserMenu` (identity,
+appearance switch, rows).
+
+### Menus: action vs single choice
+
+`ContextMenu` and `Menu` serve two kinds of list, and the row spacing says which one it is.
+
+- **Action menu** (Edit · Duplicate · Delete): no item is selected. Rows are flush (`gap: 0`); only the
+  hovered row is filled.
+- **Single-choice menu** (section switcher, language picker): pass `selected: true` on the current item. It
+  gets a `--bg-hover` fill and `--weight-medium` `--text-heading` — **no checkmark**, the fill is the
+  mark. Rows are announced as `menuitemradio` with `aria-checked`. As soon as any item is selected the
+  rows are spaced **2px apart** (`gap: 2px`), the same rhythm as `Sidebar`, `Tree` and `DocTree`, so a
+  hovered row's fill never runs into the selected row's fill.
+
+Dividers keep their 4px top and bottom margin in both kinds, independent of the row gap. Don't mix the
+two: a menu that both switches state and runs actions puts the actions after a divider, and the choice
+rows still carry `selected`.
+
 ### Table headers
 
 A header cell is the **same size as its data cells**, weight 600, `--text-secondary`, sentence
@@ -270,6 +312,7 @@ so two controls that share a row can never disagree. `md` is the default on `:ro
 | `--cell-px` | 8 | 12 | 16 | horizontal padding of a table cell |
 | `--check-size` | 14 | 16 | 16 | checkbox and radio box |
 | `--tag-h` | 20 | 24 | 28 | `Tag` |
+| `--count-h` | 16 | 18 | 20 | count badge beside a segment / pill label |
 | `--switch-w` × `--switch-h` | 28 × 16 | 36 × 20 | 44 × 24 | `Switch` track |
 
 Where each tier belongs:
@@ -412,7 +455,7 @@ The list that prevents the most rework. These are absolute.
 - **Do not show a drop indicator where the drop is impossible.** No half-row boxes on a
   container, no insert rules on a node that can't take children.
 - **Do not build a new primitive when one exists.** Check the component index in
-  `INTEGRATION.md` first — there are 117.
+  `INTEGRATION.md` first — there are 120.
 - **Do not use emoji as icons.** Use `<Icon name="..." />` (330 glyphs) or `<Unicon>` (1,206).
 - **Do not invent new component variants.** If `Button` lacks the variant you want, that is a
   design-system request, not a local override.

package/INTEGRATION.md

@@ -31,7 +31,7 @@ Not using a registry yet? A git dependency works with no publishing at all — t
 has no build step, so npm can use the checkout as-is:
 
 ```json
-"@keyfunc/keybricks-ds": "git+ssh://git@gitlab.epm2demo.cn/Felix/keybricks-ds.git#v2.3.1"
+"@keyfunc/keybricks-ds": "git+ssh://git@gitlab.epm2demo.cn/Felix/keybricks-ds.git#v2.4.0"
 ```
 
 **Source-only package.** `.jsx` and `.vue` files are published as authored, so your
@@ -162,7 +162,7 @@ Text, weight and tracking follow the tier through `--control-text` / `--control-
 weight becomes 600 and all tracking is 0 — nothing to configure. `DESIGN.md` has the full token
 table and the rules behind it.
 
-## Component index (117 components)
+## Component index (120 components)
 Import path is `@keyfunc/keybricks-ds/components/<group>/<Name>.jsx` (React) or `.vue` (Vue 3).
 Every component has a sibling `.d.ts` with its full props contract, and each group has a
 `.prompt.md` with usage notes.
@@ -238,7 +238,9 @@ import Textarea from '@keyfunc/keybricks-ds/components/forms/Textarea.vue'
 | Component | What it's for |
 | --- | --- |
 | `Sidebar` | The app's primary nav: collapsible sections, active state, footer items. `KEYBRICKS_NAV` is the product's real nav tree. |
+| `SidePanel` | 240px panel docked beside the sidebar (Documents, Management), in the rail's tone. |
 | `TopBar` | Global header — search, notifications, theme toggle, avatar. |
+| `UserMenu` | Account menu from the top bar's user trigger: identity, appearance switch, rows. |
 | `PageHeading` | Page title with optional subtitle and right-aligned actions. |
 | `PageToolbar` | Secondary bar under the heading: filters, view toggles, bulk actions. |
 | `Breadcrumb` | Path trail; collapses to an ellipsis dropdown past `maxItems`. |
@@ -249,9 +251,10 @@ import Textarea from '@keyfunc/keybricks-ds/components/forms/Textarea.vue'
 ### `tabs/` — switching views
 | Component | What it's for |
 | --- | --- |
-| `Tabs` | Page-level underline tabs. |
-| `PanelTabs` | Compact tabs inside a detail panel or drawer. |
-| `PillTabs` | Filter/status tabs as pills. |
+| `Tabs` | Page-level underline tabs; `{ label, count }` adds a count badge. |
+| `PanelTabs` | Compact tabs inside a detail panel or drawer; `{ label, count }` adds a count badge. |
+| `PillTabs` | Filter/status tabs as pills; `{ label, count }` adds a count badge. |
+| `CountBadge` | The count badge beside a segment / pill label (`--count-h`, 12px tabular figures); used by `SegmentedControl` and `PillTabs`, exported for custom filter bars. |
 | `SegmentedControl` | Switches views of the same data, applies instantly — not a saved form value (`RadioGroup`) and not page navigation (`Tabs`). Reads the size tier, `icon` per option, `iconOnly`, per-option or whole-control `disabled`, `fullWidth`. ← → keyboard. |
 | `ViewToggle` | List/grid icon toggle. |
 
@@ -490,7 +493,7 @@ a migration note in the release. Token renames are major because your own code r
 Pin a minor range and update deliberately:
 
 ```json
-"@keyfunc/keybricks-ds": "~2.3.1"
+"@keyfunc/keybricks-ds": "~2.4.0"
 ```
 
 ### Migrating from 1.x to 2.0
@@ -516,6 +519,21 @@ Pin a minor range and update deliberately:
 - **Tokens outside CSS.** `tokens.json` / `tokens.js` / `tokens.d.ts` gained the tier tokens
   (`--control-*`, `--bar-h`, `--group-gap`, …) — 352 light tokens in all (2.0.2 adds `--danger-soft-hover`).
 
+### 2.4.0
+
+- **App Chrome matches the product.** `Sidebar`: 56px brand head without a rule, `--text-md` brand, a 2px-gap list, `trailing: true` items with a chevron (they open a side panel), Collapse / Expand item (chevron-left / panel-left), pinned footer and an optional `version` line. New `tone` prop — `"recessed"` (grey rail, active item a white tile with a hairline ring; **the new default**), `"flush"` (the old white look), `"contrast"` (dark-scoped rail), `"custom"` + `color` (`SIDEBAR_COLORS` or any hex). `KEYBRICKS_NAV` is the product's nav (Home … Task Execution); new `KEYBRICKS_NAV_FOOTER` (Management, Knowledge Base) is the default footer (was Help / Settings / Dark Mode) and `KEYBRICKS_MGMT` holds the Management panel groups. To keep the old look pass `tone="flush"` and your own `footerItems`.
+- **Data-source logos:** 17 logo images (databases, SAP, protocols, file types) in `assets/logos/datasource/<id>.png`, 500×500 PNG, listed on the new *Data Source Logos* icons page. They are plain images, not `Icon` glyphs — use them with `<img>`.
+- **New `SidePanel`**: the 240px panel docked beside the sidebar (Documents, Management), same tone as the rail, opens from 0 width with a fade; 56px header with title, actions and close.
+- **`TopBar`**: dark **AI Assistant** (`ai` icon) first, then notifications and help `IconButton`s, then a user trigger (`user={{ name, email }}`) that opens a menu. The bell is no longer `lg`. **New `UserMenu`**: avatar, name, email, an Appearance row (icon-only light / dark / system) and menu rows.
+
+- **`ContextMenu` / `Menu` single-choice state.** Items accept `selected: true` (section switcher, language picker): `--bg-hover` fill, `--weight-medium` `--text-heading`, no checkmark; rows become `menuitemradio` with `aria-checked`. When any item is selected the rows are spaced 2px apart (as in `Sidebar`, `Tree`, `DocTree`); action menus with nothing selected keep flush rows. Dividers keep 4px above and below.
+
+- **Docs:** new *Icon Usage* page at the top of Icons (monochrome vs coloured glyphs: IconTile hues, Tree/DocTree document hues, status, marks). The documentation site itself now follows the system rules — neutral selected segments, sentence-case labels, sm-tier toolbar controls, 32px Sidebar-spec nav rows.
+### 2.3.2
+
+- **Counts on `Tabs`, `PanelTabs`, `PillTabs` and `SegmentedControl`.** Tabs / options accept `{ label, count?, showZero? }`; a count renders as a `CountBadge` 6px right of the label — `--count-h` tall (new tier token: sm 16 · md 18 · lg 20), 6px sides, full radius, 12px tabular figures; fill `--neutral-alpha-8` on any surface, text `--text-body`, `--text-heading` when selected. 0 or no count hides it; `showZero` (control or option) draws a muted 0. Selection is still matched by label. `CountBadge` is exported (React `Tabs.jsx`, Vue `CountBadge.vue`).
+- Additive only.
+
 ### 2.3.1
 
 - **`Table` row open, tree rows and labels.** `onRowOpen(row, index, event)` (Vue `@row-open`) makes the icon tile and title of a two-line cell open the row (hand cursor; Enter / Space on the title). `tree` with nested `children` (or `hasChildren` for lazy rows) indents the two-line column 24px per level with an expand arrow — `expandedKeys` / `defaultExpandedKeys` / `onExpandChange(row, expanded, keys)` (Vue `v-model:expandedKeys`, `@expand-change`), `rowKey` (default `id`); sorting reorders siblings only. `labels: { sortAsc, sortDesc, sortClear, more, expand, collapse }` translates every word the table draws (English by default). Indices reported by selection and callbacks are depth-first over all rows — unchanged for flat tables.

package/_adherence.oxlintrc.json

@@ -17,6 +17,7 @@
           {
             "group": [
               "assets/icons/**",
+              "changelog.js",
               "components/**",
               "components/_shared/**",
               "components/buttons/**",
@@ -29,6 +30,7 @@
               "components/navigation/**",
               "components/pipeline/**",
               "components/tabs/**",
+              "covers.js",
               "site-nav.js",
               "tokens/**"
             ],
@@ -428,8 +430,8 @@
         "message": "<SearchInput> size must be one of 'sm' | 'md' | 'lg'."
       },
       {
-        "selector": "JSXOpeningElement[name.name='SegmentedControl'] > JSXAttribute > JSXIdentifier[name!=/^(?:options|value|onChange|size|iconOnly|disabled|fullWidth|style|key|ref|className|style|children)$/]",
-        "message": "<SegmentedControl> doesn't accept that prop. Declared props: options, value, onChange, size, iconOnly, disabled, fullWidth, style."
+        "selector": "JSXOpeningElement[name.name='SegmentedControl'] > JSXAttribute > JSXIdentifier[name!=/^(?:options|value|onChange|size|iconOnly|disabled|fullWidth|showZero|style|key|ref|className|style|children)$/]",
+        "message": "<SegmentedControl> doesn't accept that prop. Declared props: options, value, onChange, size, iconOnly, disabled, fullWidth, showZero, style."
       },
       {
         "selector": "JSXOpeningElement[name.name='SegmentedControl'] > JSXAttribute[name.name='size'] > Literal[value!=/^(?:sm|md|lg)$/]",
@@ -444,8 +446,20 @@
         "message": "<Select> size must be one of 'sm' | 'md' | 'lg'."
       },
       {
-        "selector": "JSXOpeningElement[name.name='SidebarItem'] > JSXAttribute > JSXIdentifier[name!=/^(?:icon|label|children|open|key|ref|className|style|children)$/]",
-        "message": "<SidebarItem> doesn't accept that prop. Declared props: icon, label, children, open."
+        "selector": "JSXOpeningElement[name.name='SidebarItem'] > JSXAttribute > JSXIdentifier[name!=/^(?:icon|label|trailing|children|key|ref|className|style|children)$/]",
+        "message": "<SidebarItem> doesn't accept that prop. Declared props: icon, label, trailing, children."
+      },
+      {
+        "selector": "JSXOpeningElement[name.name='SidePanel'] > JSXAttribute > JSXIdentifier[name!=/^(?:open|title|actions|onClose|closeLabel|closeIcon|tone|color|width|size|children|style|key|ref|className|style|children)$/]",
+        "message": "<SidePanel> doesn't accept that prop. Declared props: open, title, actions, onClose, closeLabel, closeIcon, tone, color, width, size, children, style."
+      },
+      {
+        "selector": "JSXOpeningElement[name.name='SidePanel'] > JSXAttribute[name.name='tone'] > Literal[value!=/^(?:recessed|flush|contrast|custom)$/]",
+        "message": "<SidePanel> tone must be one of 'recessed' | 'flush' | 'contrast' | 'custom'."
+      },
+      {
+        "selector": "JSXOpeningElement[name.name='SidePanel'] > JSXAttribute[name.name='size'] > Literal[value!=/^(?:sm|md|lg)$/]",
+        "message": "<SidePanel> size must be one of 'sm' | 'md' | 'lg'."
       },
       {
         "selector": "JSXOpeningElement[name.name='Slider'] > JSXAttribute > JSXIdentifier[name!=/^(?:value|min|max|step|labels|showValue|unit|disabled|width|onChange|style|key|ref|className|style|children)$/]",
@@ -512,12 +526,8 @@
         "message": "<DataTableTwoLine> doesn't accept that prop. Declared props: icon, hue, description, mark, more."
       },
       {
-        "selector": "JSXOpeningElement[name.name='Tabs'] > JSXAttribute > JSXIdentifier[name!=/^(?:tabs|active|onChange|size|style|key|ref|className|style|children)$/]",
-        "message": "<Tabs> doesn't accept that prop. Declared props: tabs, active, onChange, size, style."
-      },
-      {
-        "selector": "JSXOpeningElement[name.name='Tabs'] > JSXAttribute[name.name='size'] > Literal[value!=/^(?:sm|md|lg)$/]",
-        "message": "<Tabs> size must be one of 'sm' | 'md' | 'lg'."
+        "selector": "JSXOpeningElement[name.name='TabItem'] > JSXAttribute > JSXIdentifier[name!=/^(?:label|count|showZero|key|ref|className|style|children)$/]",
+        "message": "<TabItem> doesn't accept that prop. Declared props: label, count, showZero."
       },
       {
         "selector": "JSXOpeningElement[name.name='Tag'] > JSXAttribute > JSXIdentifier[name!=/^(?:children|size|onRemove|tone|style|key|ref|className|style|children)$/]",
@@ -540,8 +550,8 @@
         "message": "<TimelineItem> tone must be one of 'success' | 'danger' | 'warning' | 'info' | 'neutral'."
       },
       {
-        "selector": "JSXOpeningElement[name.name='TopBar'] > JSXAttribute > JSXIdentifier[name!=/^(?:placeholder|actions|onSearch|style|key|ref|className|style|children)$/]",
-        "message": "<TopBar> doesn't accept that prop. Declared props: placeholder, actions, onSearch, style."
+        "selector": "JSXOpeningElement[name.name='TopBar'] > JSXAttribute > JSXIdentifier[name!=/^(?:placeholder|onSearch|actions|aiLabel|onAi|onNotifications|onHelp|notificationsLabel|helpLabel|user|userMenu|style|key|ref|className|style|children)$/]",
+        "message": "<TopBar> doesn't accept that prop. Declared props: placeholder, onSearch, actions, aiLabel, onAi, onNotifications, onHelp, notificationsLabel, helpLabel, user, userMenu, style."
       },
       {
         "selector": "JSXOpeningElement[name.name='TreeItem'] > JSXAttribute > JSXIdentifier[name!=/^(?:key|title|label|icon|hue|count|tag|children|disabled|disableCheckbox|selectable|checkable|isLeaf|key|ref|className|style|children)$/]",
@@ -799,6 +809,9 @@
       "SidebarItem": {
         "replaces": []
       },
+      "SidePanel": {
+        "replaces": []
+      },
       "Slider": {
         "replaces": []
       },
@@ -826,7 +839,7 @@
       "DataTableTwoLine": {
         "replaces": []
       },
-      "Tabs": {
+      "TabItem": {
         "replaces": []
       },
       "Tag": {
@@ -949,6 +962,7 @@
       "--control-px",
       "--control-text",
       "--control-tracking",
+      "--count-h",
       "--cyan-100",
       "--cyan-200",
       "--cyan-300",
@@ -1530,6 +1544,7 @@
       "--cell-px": "spacing",
       "--check-size": "spacing",
       "--tag-h": "spacing",
+      "--count-h": "spacing",
       "--switch-w": "spacing",
       "--switch-h": "spacing",
       "--title-cell-py": "spacing",

package/components/_cards/app-chrome.card.html

@@ -1,4 +1,4 @@
-<!-- @dsCard group="Components" viewport="700x510" name="App Chrome" subtitle="Sidebar · TopBar · PageToolbar · DocTree" -->
+<!-- @dsCard group="Components" viewport="700x1490" name="App Chrome" subtitle="Sidebar tones · SidePanel · TopBar · UserMenu · PageToolbar" -->
 <!DOCTYPE html>
 <html><head><meta charset="utf-8"><script src="../_shared/frame-theme.js"></script><link rel="stylesheet" href="../../styles.css"><link rel="stylesheet" href="../../tokens/hover.css"><link rel="stylesheet" href="../_shared/card-kit.css">
 <script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
@@ -9,28 +9,40 @@
 <style>body{margin:0;background:var(--bg-app);font-family:var(--font-sans);overflow:hidden;box-sizing:border-box;padding:18px}</style></head>
 <body><div id="root"></div>
 <script type="text/babel">
-const { Sidebar, KEYBRICKS_NAV, TopBar, PageToolbar, DocTree, Button } = window.KeybricksDesignSystem_71231a;
+const { Sidebar, SidePanel, TopBar, UserMenu, PageToolbar, SegmentedControl, SearchInput, Tree, Button, IconButton, SIDEBAR_COLORS, KEYBRICKS_MGMT } = window.KeybricksDesignSystem_71231a;
+const LOGO = "../../assets/keybricks-logo.png";
 function Sheet(){
-  const [active,setActive]=React.useState("Home");
-  const [col,setCol]=React.useState(false);
-  return <div style={{display:"flex",height:420,overflow:"hidden"}}>
-    <Sidebar items={KEYBRICKS_NAV} active={active} onSelect={setActive} collapsed={col} onToggleCollapse={()=>setCol(!col)} logo="../../assets/keybricks-logo.png"/>
-    <DocTree active="Financial Analysis" items={[
-      {label:"Q1 2026",kind:"folder"},{label:"Q4 2025",kind:"folder"},
-      {label:"Financial Analysis",hue:"orange"},{label:"Revenue Analysis",hue:"green"},
-      {label:"Budget 2026",kind:"folder"},{label:"Monthly Journal",hue:"purple",icon:"book-open"},{label:"Variance Report",hue:"blue"},
-    ]}/>
-    <div style={{flex:1,display:"flex",flexDirection:"column",minWidth:0}}>
-      <TopBar/>
-      <PageToolbar title="Oracle Adapter" onBack={()=>{}} actions={<React.Fragment>
-        <Button variant="ghost" icon="settings-2">Custom Parameters</Button>
-        <Button variant="ghost" icon="play">Run Test</Button>
-        <Button icon="send">Submit</Button>
-      </React.Fragment>}/>
-      <div style={{flex:1}}></div>
-    </div>
+  const [active,setActive]=React.useState("Home"),[col,setCol]=React.useState(true),[panel,setPanel]=React.useState(null),[tab,setTab]=React.useState("All"),[theme,setTheme]=React.useState("System");
+  const pick=(l)=>{ if(l==="Documents"||l==="Management"){ setPanel(panel===l?null:l); } else { setActive(l); setPanel(null); } };
+  return <div style={{display:"flex",flexDirection:"column",gap:28}}>
+    <section><div className="kb-h">Shell — Sidebar (recessed) · SidePanel · TopBar</div>
+      <div style={{overflowX:"auto",border:"1px solid var(--border-card)",borderRadius:"var(--radius-lg)"}}><div style={{display:"flex",height:580,minWidth:800,overflow:"hidden"}}>
+        <Sidebar logo={LOGO} version="Version 2.4.0" active={panel||active} onSelect={pick} collapsed={col||!!panel} onToggleCollapse={()=>setCol(!col)}/>
+        <SidePanel open={!!panel} title={panel} size="sm" onClose={()=>setPanel(null)} actions={panel==="Documents"?<IconButton icon="maximize-2" muted label="Open page"/>:null}>
+          {panel==="Documents"?<div style={{display:"flex",flexDirection:"column",gap:8,padding:"0 16px 8px"}}>
+            <SegmentedControl fullWidth options={["Recent","Favorites","All"]} value={tab} onChange={setTab}/>
+            <SearchInput bare placeholder="Search documents..."/>
+            <Tree showIcon defaultExpanded={["b"]} items={[{key:"b",title:"Budget 2026",children:[{key:"b1",title:"Opex by Department"},{key:"b2",title:"Headcount Plan"}]},{key:"c",title:"Consolidation"}]}/>
+          </div>:<div style={{display:"flex",flexDirection:"column",gap:2,padding:8}}>{KEYBRICKS_MGMT.map(g=><div key={g.label} style={{height:36,display:"flex",alignItems:"center",gap:10,padding:"0 10px",fontSize:"var(--text-base)",color:"var(--text-body)"}}>{g.label}</div>)}</div>}
+        </SidePanel>
+        <div style={{flex:1,display:"flex",flexDirection:"column",minWidth:0}}>
+          <TopBar user={{name:"Felix Wang",email:"felix@keyfunc.com"}} userMenu={<UserMenu name="Felix Wang" email="felix@keyfunc.com" theme={theme} onThemeChange={setTheme} items={[{label:"Profile",icon:"user"},{label:"Settings",icon:"settings"},{divider:true},{label:"Sign out",icon:"log-out",danger:true}]}/>}/>
+          <PageToolbar title="Oracle Adapter" onBack={()=>{}} actions={<Button icon="send">Submit</Button>}/>
+          <div style={{flex:1,background:"var(--bg-app)"}}></div>
+        </div>
+      </div>
+      </div>
+      <div className="note">The shell is 800px wide and scrolls sideways in this card; it starts with the rail collapsed — expand it with the first item. Documents and Management carry a trailing chevron: they open a SidePanel, and the rail collapses to 64px while it is open. The user trigger opens a UserMenu with the appearance switch.</div>
+    </section>
+    <section><div className="kb-h">Tones — tone="recessed" (default) · "flush" · "contrast" · "custom"</div>
+      <div style={{display:"flex",gap:12,flexWrap:"wrap"}}>
+        {[["recessed"],["flush"],["contrast"],["custom","navy"],["custom","forest"],["custom","plum"]].map(([t,cl])=><div key={t+(cl||"")} style={{display:"flex",flexDirection:"column",gap:6}}><span className="lbl">{t}{cl?" · "+cl:""}</span>
+          <div style={{height:300,overflow:"hidden",border:"1px solid var(--border-card)",borderRadius:"var(--radius-md)"}}><Sidebar logo={LOGO} tone={t} color={cl} active="Documents" version="Version 2.4.0" items={[{icon:"house",label:"Home"},{icon:"file-text",label:"Documents",trailing:true},{icon:"database",label:"Data Integration"}]} footerItems={[{icon:"settings",label:"Management",trailing:true}]} style={{width:200}}/></div></div>)}
+      </div>
+      <div className="note">Custom colours: {Object.keys(SIDEBAR_COLORS).join(" · ")} — or any hex. Contrast and custom rails are scoped to the dark theme, so the components inside follow.</div>
+    </section>
   </div>;
 }
 ReactDOM.createRoot(document.getElementById("root")).render(<Sheet/>);
-if (window.KBViewSource) setTimeout(function(){ KBViewSource.mount("#root", [{"name":"Sidebar.jsx","path":"../navigation/Sidebar.jsx"},{"name":"TopBar.jsx","path":"../navigation/TopBar.jsx"},{"name":"DocTree.jsx","path":"../navigation/DocTree.jsx"},{"name":"Button.jsx","path":"../buttons/Button.jsx"}]); }, 0);
+if (window.KBViewSource) setTimeout(function(){ KBViewSource.mount("#root", [{"name":"Sidebar.jsx","path":"../navigation/Sidebar.jsx"},{"name":"SidePanel.jsx","path":"../navigation/SidePanel.jsx"},{"name":"TopBar.jsx","path":"../navigation/TopBar.jsx","vue":"../navigation/TopBar.vue","vueName":"TopBar.vue"},{"name":"UserMenu","path":"../navigation/TopBar.jsx","vue":"../navigation/UserMenu.vue","vueName":"UserMenu.vue"},{"name":"chrome-tones.js","path":"../navigation/chrome-tones.js","reactOnly":false}]); }, 0);
 </script></body></html>

package/components/_cards/context-menu.card.html

@@ -1,4 +1,4 @@
-<!-- @dsCard group="Components" viewport="700x920" name="Context Menu" subtitle="Icons · plain text · danger item · long list" -->
+<!-- @dsCard group="Components" viewport="700x920" name="Context Menu" subtitle="Action vs single-choice spacing · selected state · icons · plain text · danger item · long list" -->
 <!DOCTYPE html>
 <html><head><meta charset="utf-8"><script src="../_shared/frame-theme.js"></script><link rel="stylesheet" href="../../styles.css"><link rel="stylesheet" href="../../tokens/hover.css"><link rel="stylesheet" href="../_shared/card-kit.css">
 <script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
@@ -12,7 +12,12 @@
 <script type="text/babel">
 const { ContextMenu } = window.KeybricksDesignSystem_71231a;
 const { KBTiers: Tiers } = window;
-function Sheet(){return <div className="grid">
+function Sheet(){const [sec,setSec]=React.useState("Overview");const [lang,setLang]=React.useState("English");return <div className="grid">
+  <div style={{flexBasis:"100%",display:"flex",flexDirection:"column",gap:8}}><span className="lbl">Row spacing — an action menu keeps its rows flush; a single-choice menu (one item <code>selected</code>) spaces them 2px apart, so a hovered row never touches the selected one</span><div style={{display:"flex",gap:20,alignItems:"flex-start",flexWrap:"wrap"}}>
+    <div className="col"><span className="lbl">Action menu · gap 0</span><ContextMenu items={[{label:"Edit",icon:"edit-2"},{label:"Duplicate",icon:"copy"},{label:"Export",icon:"download"},{divider:true},{label:"Delete",icon:"trash-2",danger:true}]}/></div>
+    <div className="col"><span className="lbl">Single choice · gap 2 · no checkmark</span><ContextMenu items={["Overview","Data Sources","Pipelines","Reports"].map(l=>({label:l,selected:l===sec}))} onSelect={setSec}/></div>
+    <div className="col"><span className="lbl">Language picker</span><ContextMenu items={[{label:"English",selected:lang==="English"},{label:"简体中文",selected:lang==="简体中文"},{label:"日本語",selected:lang==="日本語"},{divider:true},{label:"Follow system",icon:"monitor"}]} onSelect={(l)=>l!=="Follow system"&&setLang(l)}/></div>
+  </div></div>
   <div className="col"><span className="lbl">With icons</span><ContextMenu items={[{label:"Preview",icon:"eye"},{label:"Duplicate",icon:"copy"},{divider:true},{label:"Delete",icon:"trash-2",danger:true}]}/></div>
   <div className="col"><span className="lbl">Plain text, no icons</span><ContextMenu items={[{label:"Rename"},{label:"Move to..."},{label:"Archive"}]}/></div>
   <div className="col"><span className="lbl">Danger only</span><ContextMenu items={[{label:"Remove from workflow",icon:"x",danger:true}]}/></div>

package/components/_cards/icons-0-usage.card.html

@@ -0,0 +1,88 @@
+<!-- @dsCard group="Icons" viewport="700x2250" name="Icon Usage" subtitle="Monochrome glyphs · category tiles · document hues · status · marks · icons inside components — when an icon gets colour" -->
+<!DOCTYPE html>
+<html><head><meta charset="utf-8"><script src="../_shared/frame-theme.js"></script><link rel="stylesheet" href="../../styles.css"><link rel="stylesheet" href="../../tokens/hover.css"><link rel="stylesheet" href="../_shared/card-kit.css">
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+<script src="../../_ds_bundle.js"></script>
+<script src="../_shared/card-kit.js"></script>
+<script src="../_shared/view-source.js"></script>
+<style>body{margin:0;background:var(--bg-surface)}.cap{display:flex;flex-direction:column;align-items:center;gap:6px;min-width:56px}.cap span{font-size:var(--text-xs);line-height:var(--leading-xs);color:var(--text-secondary);white-space:nowrap}.rules{margin:0;padding-left:18px;display:flex;flex-direction:column;gap:6px;font-size:var(--text-base);line-height:var(--leading-base);color:var(--text-body)}.rules code{font-size:12px;white-space:nowrap}</style></head>
+<body><div id="root"></div>
+<script type="text/babel">
+const { Icon, IconTile, StatusBadge, Alert, Button, IconButton, PaletteItem, ListRow, ActivityItem, DocTree } = window.KeybricksDesignSystem_71231a;
+const LEAF = [["orange", "var(--cat-transform)"], ["green", "var(--cat-source)"], ["purple", "var(--cat-merge)"], ["blue", "var(--info-fg)"], ["teal", "var(--cat-output)"], ["gray", "var(--text-muted)"]];
+const HUES = [["source", "table"], ["join", "shuffle"], ["transform", "funnel"], ["merge", "merge"], ["output", "layers"]];
+const Cap = ({ label, children }) => <div className="cap">{children}<span>{label}</span></div>;
+const Glyph = ({ name, color, label }) => <Cap label={label}><span style={{ color, display: "inline-flex" }}><Icon name={name} size={20} /></span></Cap>;
+function Sheet() {
+  return <div className="kb-sheet">
+    <KBSec title="1 · Monochrome glyph — the default" note="Almost every icon is a single-colour stroke glyph that takes the colour of its text. Colour comes from the text token, never from the icon itself.">
+      <KBRow k="text colour">
+        <Glyph name="file-text" color="var(--text-heading)" label="heading" />
+        <Glyph name="file-text" color="var(--text-body)" label="body" />
+        <Glyph name="file-text" color="var(--text-secondary)" label="secondary" />
+        <Glyph name="file-text" color="var(--text-muted)" label="muted / disabled" />
+        <Glyph name="file-text" color="var(--action-primary)" label="action" />
+      </KBRow>
+      <KBRow k="on a fill"><Button icon="download">Export</Button><Button variant="dark" icon="ai-sparkles">AI Assistant</Button><Button variant="danger" icon="trash-2">Delete</Button><IconButton icon="ellipsis" label="More" /></KBRow>
+    </KBSec>
+    <KBSec title="2 · Category tile — IconTile" note="The coloured square is a category, not decoration: each hue is one node type (--cat-*-bg behind --cat-* glyph). Dark mode swaps both for a low-alpha wash automatically.">
+      <KBRow k="palette · 40 r14">{HUES.map(([h, i]) => <Cap key={h} label={h}><IconTile icon={i} hue={h} /></Cap>)}</KBRow>
+      <KBRow k="node · 48 r16">{HUES.map(([h, i]) => <Cap key={h} label={h}><IconTile icon={i} hue={h} kind="node" /></Cap>)}</KBRow>
+      <KBRow k="row · 32 r8">
+        <Cap label="hue"><IconTile icon="table" hue="join" kind="row" /></Cap>
+        <Cap label="hue"><IconTile icon="box" hue="merge" kind="row" /></Cap>
+        <Cap label="neutral"><IconTile icon="folder" hue="neutral" kind="row" /></Cap>
+        <Cap label="no hue (hairline)"><IconTile icon="file-text" kind="row" /></Cap>
+      </KBRow>
+    </KBSec>
+    <KBSec title="3 · Document glyph — Tree / DocTree hue" note="The one place a bare glyph is coloured: a document leaf in Tree or DocTree takes a hue that tells the document type apart. Folders stay muted. Pass hue on the item; the component maps it to the token.">
+      <KBRow k="leaf hue">{LEAF.map(([h, v]) => <Cap key={h} label={h}><span style={{ color: v, display: "inline-flex" }}><Icon name="file-text" size={16} /></span></Cap>)}</KBRow>
+      <KBRow k="DocTree" style={{ display: "block" }}><div style={{ width: 240, border: "1px solid var(--border-card)", borderRadius: "var(--radius-lg)", overflow: "hidden" }}><DocTree title="Documents" active="Revenue Analysis" items={[{ label: "Q1 2026", kind: "folder" }, { label: "Revenue Analysis", hue: "green" }, { label: "Cost Allocation", hue: "orange" }, { label: "FX Rates Model", hue: "purple" }, { label: "Cash Flow Forecast", hue: "blue" }, { label: "Notes", hue: "gray" }]} /></div></KBRow>
+    </KBSec>
+    <KBSec title="4 · Status" note="Status colour is reserved for state: success, warning, danger, info, pending. The glyph sits in a solid circle (StatusBadge) or leads a tinted message (Alert).">
+      <KBRow k="StatusBadge">
+        <Cap label="success"><StatusBadge tone="success" icon="check" /></Cap>
+        <Cap label="danger"><StatusBadge tone="danger" icon="x" /></Cap>
+        <Cap label="warning"><StatusBadge tone="warning" icon="bell" /></Cap>
+        <Cap label="pending"><StatusBadge tone="pending" icon="clock" /></Cap>
+        <Cap label="info"><StatusBadge tone="info" icon="info" /></Cap>
+        <Cap label="node dot · 13"><StatusBadge tone="danger" size={13} /></Cap>
+      </KBRow>
+      <KBRow k="Alert" style={{ flexDirection: "column", alignItems: "stretch", gap: 8 }}>
+        <Alert tone="info" title="Import scheduled">Runs daily at 06:00.</Alert>
+        <Alert tone="success" title="Sync complete">312 rows updated.</Alert>
+        <Alert tone="warning" title="Mapping incomplete">2 accounts have no target.</Alert>
+        <Alert tone="danger" title="Connection failed">The Oracle source did not respond.</Alert>
+      </KBRow>
+    </KBSec>
+    <KBSec title="5 · Marks" note="A 14px mark next to a title flags one property of the row. Favourite is the only filled glyph in the system.">
+      <KBRow k="favourite">
+        <span style={{ display: "inline-flex", alignItems: "center", gap: 4, fontSize: "var(--text-base)", color: "var(--text-heading)" }}>FX Rates Model<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" stroke="currentColor" strokeWidth="2" strokeLinejoin="round" style={{ color: "var(--warning)" }}><path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z" /></svg></span>
+        <span style={{ fontSize: "var(--text-xs)", color: "var(--text-secondary)" }}>Table <code>mark: "favorite"</code> · --warning</span>
+      </KBRow>
+      <KBRow k="AI">
+        <Glyph name="ai" color="var(--action-primary)" label="ai" />
+        <Glyph name="ai-sparkles" color="var(--action-primary)" label="ai-sparkles" />
+      </KBRow>
+    </KBSec>
+    <KBSec title="6 · Inside components" note="These components choose the tile and colour for you — pass an icon and, where it applies, a hue.">
+      <KBRow k="PaletteItem"><div style={{ display: "flex", gap: 8 }}><PaletteItem icon="table" hue="source" label="Detail Sheet" /><PaletteItem icon="shuffle" hue="join" label="Association Match" /><PaletteItem icon="funnel" hue="transform" label="Filter" /><PaletteItem icon="layers" hue="output" label="Output" /></div></KBRow>
+      <KBRow k="ActivityItem" style={{ display: "block" }}><ActivityItem icon="upload" title="Opening balances imported" meta="Felix Wang · 09:10" action="Open" /></KBRow>
+      <KBRow k="ListRow" style={{ display: "block" }}><ListRow icon="workflow" title="Month-end close" meta="6 steps" trailing="6" /></KBRow>
+    </KBSec>
+    <KBSec title="Rules">
+      <ul className="rules">
+        <li>Default to a monochrome glyph in the text's own colour. Add colour only when it means something.</li>
+        <li>Category hue → <code>IconTile</code> (or a component that uses it). A bare glyph gets a hue only as a document leaf, through the <code>hue</code> of a Tree or DocTree item.</li>
+        <li>Status colour only for state, always with a shape (circle, tinted message) — never colour alone.</li>
+        <li>Tile and glyph always come as a pair: <code>--cat-x-bg</code> behind <code>--cat-x</code>. Don't mix hues or invent tints.</li>
+        <li>Glyphs on a solid fill (buttons, status badges) use <code>--on-accent</code>; components do this for you.</li>
+      </ul>
+    </KBSec>
+  </div>;
+}
+ReactDOM.createRoot(document.getElementById("root")).render(<Sheet />);
+if (window.KBViewSource) setTimeout(function () { KBViewSource.mount("#root", [{ "name": "Badge.jsx (IconTile · StatusBadge)", "path": "../display/Badge.jsx", "vue": "../display/IconTile.vue", "vueName": "IconTile.vue" }, { "name": "Icon.jsx", "path": "../icons/Icon.jsx" }]); }, 0);
+</script></body></html>

package/components/_cards/icons-4-datasource.card.html

@@ -0,0 +1,5 @@
+<!-- @dsCard group="Icons" viewport="700x660" name="Data Source Logos" subtitle="17 data-source logo images in assets/logos/datasource/" -->
+<!DOCTYPE html>
+<html><head><meta charset="utf-8"><script src="../_shared/frame-theme.js"></script><link rel="stylesheet" href="../../styles.css">
+<style>body{margin:0;background:var(--bg-surface);padding:24px;box-sizing:border-box;font-family:var(--font-sans)}.g{display:grid;grid-template-columns:repeat(auto-fill,minmax(112px,1fr));gap:12px}.t{display:flex;flex-direction:column;align-items:center;gap:8px;padding:12px 8px;border:1px solid var(--border-card);border-radius:var(--radius-lg)}.t img{width:64px;height:64px;border-radius:var(--radius-lg);display:block}.n{font-size:var(--text-xs);line-height:var(--leading-xs);color:var(--text-heading);text-align:center}.f{font-size:11px;line-height:16px;color:var(--text-secondary)}</style></head>
+<body><div class="g"><div class="t"><img src="../../assets/logos/datasource/oracle.png" alt="Oracle"><span class="n">Oracle</span><span class="f">oracle.png</span></div><div class="t"><img src="../../assets/logos/datasource/sap.png" alt="SAP"><span class="n">SAP</span><span class="f">sap.png</span></div><div class="t"><img src="../../assets/logos/datasource/sap-alt.png" alt="SAP (alternate)"><span class="n">SAP (alternate)</span><span class="f">sap-alt.png</span></div><div class="t"><img src="../../assets/logos/datasource/sql-server.png" alt="SQL Server"><span class="n">SQL Server</span><span class="f">sql-server.png</span></div><div class="t"><img src="../../assets/logos/datasource/mysql.png" alt="MySQL"><span class="n">MySQL</span><span class="f">mysql.png</span></div><div class="t"><img src="../../assets/logos/datasource/mariadb.png" alt="MariaDB"><span class="n">MariaDB</span><span class="f">mariadb.png</span></div><div class="t"><img src="../../assets/logos/datasource/postgresql.png" alt="PostgreSQL"><span class="n">PostgreSQL</span><span class="f">postgresql.png</span></div><div class="t"><img src="../../assets/logos/datasource/mongodb.png" alt="MongoDB"><span class="n">MongoDB</span><span class="f">mongodb.png</span></div><div class="t"><img src="../../assets/logos/datasource/hive.png" alt="Hive"><span class="n">Hive</span><span class="f">hive.png</span></div><div class="t"><img src="../../assets/logos/datasource/odbc.png" alt="ODBC"><span class="n">ODBC</span><span class="f">odbc.png</span></div><div class="t"><img src="../../assets/logos/datasource/rest-api.png" alt="REST API"><span class="n">REST API</span><span class="f">rest-api.png</span></div><div class="t"><img src="../../assets/logos/datasource/soap.png" alt="SOAP"><span class="n">SOAP</span><span class="f">soap.png</span></div><div class="t"><img src="../../assets/logos/datasource/ftp.png" alt="FTP"><span class="n">FTP</span><span class="f">ftp.png</span></div><div class="t"><img src="../../assets/logos/datasource/excel.png" alt="Excel"><span class="n">Excel</span><span class="f">excel.png</span></div><div class="t"><img src="../../assets/logos/datasource/json.png" alt="JSON"><span class="n">JSON</span><span class="f">json.png</span></div><div class="t"><img src="../../assets/logos/datasource/dat.png" alt="DAT"><span class="n">DAT</span><span class="f">dat.png</span></div><div class="t"><img src="../../assets/logos/datasource/hierarchy.png" alt="Hierarchy"><span class="n">Hierarchy</span><span class="f">hierarchy.png</span></div></div></body></html>

package/components/_cards/segmented-control.card.html

@@ -1,4 +1,4 @@
-<!-- @dsCard group="Components" viewport="700x870" name="Segmented Control" subtitle="Mutually exclusive views in one inset track — md/sm · icons · icon-only · disabled option · full width · ViewToggle" -->
+<!-- @dsCard group="Components" viewport="700x1260" name="Segmented Control" subtitle="Mutually exclusive views in one inset track — md/sm · counts · icons · icon-only · disabled option · full width · ViewToggle" -->
 <!DOCTYPE html>
 <html><head><meta charset="utf-8"><script src="../_shared/frame-theme.js"></script><link rel="stylesheet" href="../../styles.css"><link rel="stylesheet" href="../../tokens/hover.css"><link rel="stylesheet" href="../_shared/card-kit.css">
 <script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
@@ -14,11 +14,17 @@ const { SegmentedControl, ViewToggle } = window.KeybricksDesignSystem_71231a;
 const { KBTiers: Tiers } = window;
 const Case = ({ k, children }) => <div className="case"><span className="k">{k}</span><div className="v">{children}</div></div>;
 function Sheet() {
-  const [a, setA] = React.useState("Grid"), [b, setB] = React.useState("Last 30 days"), [c, setC] = React.useState("Table"), [d, setD] = React.useState("Actual"), [e, setE] = React.useState("Month"), [f, setF] = React.useState("Overview"), [v, setV] = React.useState("grid");
+  const [n, setN] = React.useState("Submission"), [a, setA] = React.useState("Grid"), [b, setB] = React.useState("Last 30 days"), [c, setC] = React.useState("Table"), [d, setD] = React.useState("Actual"), [e, setE] = React.useState("Month"), [f, setF] = React.useState("Overview"), [v, setV] = React.useState("grid");
   return <div>
     <div className="kb-h kb-h-gap">Sizes</div>
     <Tiers stack style={{gridTemplateColumns:"56px repeat(2,max-content)",columnGap:16}} init={(l)=>l==="en"?"Last 30 days":"近 30 天"} render={(t,l,v,set)=><SegmentedControl options={l==="en"?["Last 7 days","Last 30 days","Quarter"]:["近 7 天","近 30 天","本季度"]} value={v} onChange={set}/>}/>
 
+    <div className="kb-h kb-h-gap">Counts</div>
+    <Case k="count on an option"><SegmentedControl options={[{ label: "Submission", count: 3 }, { label: "Review", count: 12 }, { label: "Approved", count: 0 }]} value={n} onChange={setN} /></Case>
+    <Case k="showZero · muted 0"><SegmentedControl showZero options={[{ label: "Submission", count: 3 }, { label: "Review", count: 12 }, { label: "Approved", count: 0 }]} value={n} onChange={setN} /></Case>
+    <Case k="sizes"><div style={{ display: "flex", flexDirection: "column", gap: 12, alignItems: "flex-start" }}>{["sm", "md", "lg"].map(s => <SegmentedControl key={s} size={s} options={[{ label: "Submission", count: 3 }, { label: "Review", count: 12 }, { label: "Approved" }]} value={n} onChange={setN} />)}</div></Case>
+    <div className="note">The badge sits 6px right of the label: <code>--count-h</code> tall (sm 16 · md 18 · lg 20), 6px sides, full radius, 12px tabular figures. The fill is the alpha wash <code>--neutral-alpha-8</code>, so it shows on the white active segment and the #fafafa track alike; the text tells them apart — <code>--text-heading</code> selected, <code>--text-body</code> unselected. A count of 0 or none hides it; <code>showZero</code> (on the control or the option) draws a muted 0. The selected value is still matched by label.</div>
+
     <div className="kb-h kb-h-gap">With icons</div>
     <Case k="icon + label"><SegmentedControl options={[{ label: "List", icon: "list" }, { label: "Grid", icon: "layout-grid" }]} value={a} onChange={setA} /></Case>
     <Case k="icon only · aria label"><SegmentedControl options={[{ icon: "table", label: "Table" }, { icon: "chart-column", label: "Chart" }, { icon: "code", label: "JSON" }]} iconOnly value={c} onChange={setC} /></Case>
@@ -36,5 +42,5 @@ function Sheet() {
   </div>;
 }
 ReactDOM.createRoot(document.getElementById("root")).render(<Sheet/>);
-if (window.KBViewSource) setTimeout(function(){ KBViewSource.mount("#root", [{"name":"SegmentedControl.jsx","path":"../tabs/SegmentedControl.jsx"},{"name":"ViewToggle.jsx","path":"../tabs/ViewToggle.jsx"}]); }, 0);
+if (window.KBViewSource) setTimeout(function(){ KBViewSource.mount("#root", [{"name":"SegmentedControl.jsx","path":"../tabs/SegmentedControl.jsx"},{"name":"Tabs.jsx (CountBadge)","path":"../tabs/Tabs.jsx","vue":"../tabs/CountBadge.vue","vueName":"CountBadge.vue"},{"name":"ViewToggle.jsx","path":"../tabs/ViewToggle.jsx"}]); }, 0);
 </script></body></html>