@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScToggleSwitch.md

@@ -0,0 +1,229 @@
+---
+component: ScToggleSwitch
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div
+tags: [toggle, switch, on-off, enable, disable, setting, instant-apply, boolean]
+related: [ScCheckbox, ScAppField, ScCatalogixInvite, ScPhtogenixInvite, ScArtifaxInvite]
+do_not_confuse_with: [ScCheckbox, ScAppSwitchPanel, ScWorkspaceSwitchCard, ScTabSwitcher, ScAppField]
+used_by: [catalogix]
+---
+
+# ScToggleSwitch
+
+**The on/off switch — a 40×24 pill with a knob.** Two hand-traced SVGs (one per
+state) inside a clickable `<div>`. Use it for settings that apply the moment they
+are flipped; use `ScCheckbox` for values a form stages until Save.
+
+## TL;DR for agents
+
+- **Reach for it when:** a single boolean setting applies immediately — enable a
+  feature, mute a rule, turn on an app for a user.
+- **Don't reach for it when:** the value is staged behind a Save button
+  (→ `ScCheckbox` / `ScCheckField`), or you are building the CXO app-permission block
+  (→ `ScAppField`, which already renders these).
+- **Four things that will bite you:**
+  1. `active` is the **string** `"true"`/`"false"`, not a boolean. ⚠️ Prefer `checked`.
+  2. `checked` **overrides** `active` whenever it is not `undefined`.
+  3. The OFF artwork is 41×25 and ON is 40×24 — the element **changes size by half a
+     pixel** as you toggle. Wrap it if you need a stable box.
+  4. There is **no animation**. The two states are separate SVGs; the knob jumps.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScToggleSwitch } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScToggleSwitch checked={isEnabled} onToggle={setIsEnabled} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `checked` | `boolean` | – | The modern, controlled input. **Wins over `active`** when not `undefined`. Use this. |
+| `active` | `"true"` \| `"false"` | `"false"` | ⚠️ **String** union, the Figma-traced legacy axis. `active="false"` means OFF despite being a truthy string. |
+| `disabled` | `boolean` | `false` | `cursor: not-allowed` + `opacity: 0.5`; the click handler early-returns before `onToggle` **and** your `onClick`. Does not stop propagation. |
+| `onToggle` | `(active: boolean) => void` | – | Fires with the *next* value. The handler you want. |
+| `className` | `string` | – | Concatenated between the base and state classes. |
+| `...props` | `Omit<HTMLAttributes<HTMLDivElement>, "onToggle">` | – | Spread onto the root. `onClick` and `style` are **re-applied after** the spread, so the component's own versions win — but yours are still honoured (see Gotchas 5 and 6). |
+
+### What renders in each state
+
+| Effective state | Artwork | Tokens | Box |
+|---|---|---|---|
+| ON | 40×24 rounded track, knob at `cx=28` | track `--alias-fill-base-base`, knob `--alias-text---icons-inverse` | `2.5rem × 1.5rem` |
+| OFF | 41×25 track + hairline outline, knob at `cx≈12` | track `--alias-fill-neutral-neutral`, outline `--alias-border-divider`, knob `--alias-fill-neutral-neutralactive` | `2.53125rem × 1.53125rem` |
+
+Effective state is `checked !== undefined ? checked : active === "true"`.
+
+### Recipes
+
+```tsx
+// Instant-apply setting
+<ScToggleSwitch
+  checked={rule.enabled}
+  onToggle={(next) => patchRule(rule.id, { enabled: next })}
+/>
+
+// Read-only / not-yet-entitled
+<ScToggleSwitch checked={false} disabled onToggle={noop} />
+
+// Inside a labelled settings row (you own the label — the switch has none)
+<div style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+  <span>Auto-sync every night</span>
+  <ScToggleSwitch checked={autoSync} onToggle={setAutoSync} aria-label="Auto-sync" />
+</div>
+
+// Legacy event-shaped callback (the Catalogix shim), if a call site expects e.target.checked
+<ScToggleSwitch
+  checked={!!value}
+  onToggle={(next) => onChange({ target: { checked: next } })}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Catalogix settings and product screens** — via the local
+  `app/components/Toggle` shim, which replaced a native `<input type=checkbox>` +
+  CSS slider (that version didn't theme).
+- **Inside the DS's invite components** — `ScCatalogixInvite`, `ScPhtogenixInvite`
+  and `ScArtifaxInvite` each render one, and `ScAppField` composes those. If you are
+  building an app-permission block, use `ScAppField` and pass its
+  `onCatalogixToggle` / `onPhotogenixToggle` / `onArtifaxToggle` props rather than
+  nesting your own switches.
+- **Settings rows** where the change is saved immediately.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The boolean **takes effect on click** (a setting, a feature flag, an entitlement).
+- There is exactly one thing being turned on or off, with its label to the left.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A form value confirmed later with Save/Invite | `ScCheckbox` / `ScCheckField` |
+| Several booleans under one caption | `ScCheckField` |
+| Per-app enable + store selection in an invite/manage flow | `ScAppField` (composes `ScCatalogixInvite` etc.) |
+| Choosing between two *modes* (not on/off) | `ScTabField` / `ScSelectionPillGroup` |
+| Switching workspace or app | `ScWorkspaceSwitchCard` / `ScAppSwitchPanel` — "switch" in those names means navigation, not a boolean |
+| A form control that submits with a `<form>` | native `<input type="checkbox" role="switch">` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTabSwitcher` — a segmented tab bar | Not a toggle switch |
+| `ScAppSwitchPanel` / `ScWorkspaceSwitchCard` — app/workspace pickers | "Switch" as in *switch to*, not on/off |
+| `ScCheckbox` — staged boolean, has a `partial` state | This switch is two-state only |
+| `ScAppField` — the whole app-permission block | Don't rebuild it from bare switches |
+
+---
+
+## 4. Why to use it
+
+- **It themes.** Catalogix swapped its CSS slider for this precisely because the
+  hand-rolled one was baked for one theme. Track, outline and knob all come from
+  `--alias-*` tokens.
+- **Exact Figma geometry.** 40×24 track, 10px knob radius, 12px corner — traced, not
+  approximated, so every switch in the product is identical.
+- **One click contract.** `onToggle(next)` gives you the value you want to store; no
+  `e.target.checked` plumbing, no `preventDefault` dance.
+- **`disabled` is handled in one place** — cursor, opacity and the handler guard —
+  instead of three slightly different implementations per app.
+
+---
+
+## Gotchas
+
+**1. `active` is a string.** `"false"` is OFF. `active={false}` is a type error, and
+`active` with any other string silently reads as OFF.
+
+```tsx
+// WRONG — type error, and conceptually the wrong prop
+<ScToggleSwitch active={isOn} onToggle={setIsOn} />
+
+// RIGHT — use the boolean prop
+<ScToggleSwitch checked={isOn} onToggle={setIsOn} />
+```
+
+**2. `checked` overrides `active`.** Passing both means `active` is dead code. Pick
+`checked`.
+
+**3. No internal state.** `onToggle` firing does not change the artwork; you must move
+`checked` (or `active`). A switch that "doesn't respond" is almost always this.
+
+**4. It's not an `<input>`.** No `role="switch"`, no `aria-checked`, no `tabIndex`, no
+keyboard, no `name`/`value`, no form participation, and **no label** — add
+`aria-label` and your own text.
+
+**5. `onToggle` runs before your `onClick`, and both run.** The internal handler calls
+`onToggle(!isActive)` then `props.onClick?.(e)`. Don't wire the same mutation twice.
+
+**6. You cannot replace the root `onClick` or `cursor`.** `{...props}` is spread
+*before* the component's own `onClick` and `style`, so the internal ones win. Your
+`props.style` **is** merged (spread last inside the style object), and your
+`props.onClick` **is** invoked from inside — but you can't suppress the toggle by
+passing your own `onClick`. Use `disabled` for that.
+
+**7. Half-pixel size change on toggle.** OFF is `2.53125rem × 1.53125rem`, ON is
+`2.5rem × 1.5rem`. In a tightly packed flex row this shifts neighbours by a fraction
+of a pixel every flip. Wrap it in a fixed-size box if that's visible.
+
+**8. `disabled` does not stop propagation.** The click still bubbles to a parent row
+handler even though the switch ignores it.
+
+**9. No transition.** ON and OFF are two different SVG trees, so React swaps them —
+the knob teleports. Don't promise a sliding animation in a spec.
+
+**10. jsdom tests need a stub.** Host repos mock `@streamoid/ui` (see
+`catalogix/dashboard app/tests/formControls.test.jsx`, which stubs
+`ScToggleSwitch` with a div exposing `data-checked`) because the barrel import
+touches `CSS.registerProperty`.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/components/Toggle/index.jsx:17   (legacy-API shim)
+<ScToggleSwitch
+  checked={!!props.checked}
+  disabled={props.disabled}
+  onToggle={(next) =>
+    props.onChange &&
+    props.onChange({
+      target: { checked: next },
+      currentTarget: { checked: next },
+      stopPropagation: () => {},
+      preventDefault: () => {},
+    })
+  }
+/>
+```
+
+---
+
+## Related
+
+- `ScCheckbox` — the staged-value sibling; also has an indeterminate state.
+- `ScCheckField` — several staged booleans under one caption.
+- `ScAppField` — the CXO app-permission block; renders these switches for you.
+- `ScCatalogixInvite` / `ScPhtogenixInvite` / `ScArtifaxInvite` — per-app rows that embed one.

package/dist/docs/ScUsageHistoryMobile.md

@@ -0,0 +1,194 @@
+---
+component: ScUsageHistoryMobile
+exported: false
+package: "@streamoid/ui"
+category: mobile
+status: deprecated
+renders: div
+tags: [mobile, billing, usage, credits, log, row, unexported, dead-code, superseded]
+related: [UsageHistoryMobile, ScInvoiceHistoryMobile, ScBillingLogsTableList]
+do_not_confuse_with: [UsageHistoryMobile, ScInvoiceHistoryMobile, InvoiceHistoryMobile]
+---
+
+# ScUsageHistoryMobile
+
+**Do not use — this component is not shipped.** It is an earlier copy of the mobile
+credit-usage row that never made it into the public surface: it is absent from
+`src/index.ts`, so its JS is not in `dist/index.js`, its class names are not in
+`dist/index.css`, and `IScUsageHistoryMobileProps` is not in `dist/index.d.ts`.
+The shipped component is **`UsageHistoryMobile`** (no `Sc` prefix) in
+`src/SC-UsageHistoryMobile/`.
+
+## TL;DR for agents
+
+- **Reach for it when:** never. Use `UsageHistoryMobile` instead.
+- **Don't reach for it when:** always — importing `ScUsageHistoryMobile` from
+  `@streamoid/ui` fails to type-check and resolves to `undefined` at runtime.
+- **Two things that will bite you:**
+  1. **It is not exported.** Verified: `grep -c scUsageHistoryMobile dist/index.css`
+     → `0`.
+  2. **Three of its five prop names differ from the shipped twin** — `title`,
+     `usageCount`, `totalCount` became `serviceName`, `credits`, `balance`.
+
+---
+
+## 1. How to use it
+
+You don't. Import the shipped sibling:
+
+### Import
+
+```tsx
+// The component that actually ships:
+import { UsageHistoryMobile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+
+// NOT THIS — `ScUsageHistoryMobile` is not an export of @streamoid/ui
+```
+
+### Minimal usage
+
+```tsx
+<UsageHistoryMobile
+  serviceName={log.serviceName}
+  credits={log.amount.toLocaleString("en-US")}
+  userName={log.userName}
+  date={formatDate(log.createdAt)}
+  balance={log.balanceAfter.toLocaleString("en-US")}
+/>
+```
+
+### Props
+
+Documented only so you can recognise the difference when migrating a call site.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `title` | `string` | `"Artifax Generation"` | ⚠️ Demo default. **Renamed to `serviceName`** in the shipped twin. |
+| `usageCount` | `string` | `"50"` | ⚠️ Demo default. **Renamed to `credits`.** Always error-red. |
+| `userName` | `string` | `"Rohan"` | ⚠️ Demo default. Same name in the shipped twin. |
+| `date` | `string` | `"Nov 9th, 2025"` | ⚠️ Demo default. Same name in the shipped twin. |
+| `totalCount` | `string` | `"84,902"` | ⚠️ Demo default. **Renamed to `balance`.** |
+| `onClick` | `(e: React.MouseEvent) => void` | – | **Only exists here.** The shipped twin has no click handler. |
+| `className` | `string` | – | Unguarded concat — renders a literal `undefined` class when omitted. |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | – | **Only exists here.** The shipped twin accepts no extra props. |
+
+### Mapping between the two
+
+| This (unexported) | Shipped `UsageHistoryMobile` |
+|---|---|
+| `title` | `serviceName` |
+| `usageCount` | `credits` |
+| `userName` | `userName` |
+| `date` | `date` |
+| `totalCount` | `balance` |
+| `onClick` | *(none — wrap the row in your own clickable `div`)* |
+| `...props` spread | *(none — `className` only)* |
+
+Styling is equivalent: 16px padding, two flex rows, a 12px 0.5px vertical rule between
+user and date, red 16px/600 credit figure, tertiary balance. One cosmetic difference —
+this copy's vertical rule uses `--alias-border-subtle`, the shipped one uses
+`--alias-border-divider`.
+
+### Recipes
+
+```tsx
+// Migrating an old call site
+// BEFORE
+// <ScUsageHistoryMobile title={s} usageCount={c} userName={u} date={d} totalCount={b} onClick={open} />
+
+// AFTER
+<div onClick={open} className="cursor-pointer">
+  <UsageHistoryMobile serviceName={s} credits={c} userName={u} date={d} balance={b} />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere. The surface it was drawn for — the "Usage history" tab of CXO's mobile billing
+screen — is served by `UsageHistoryMobile`
+(`cxo-dashboard/src/app/components/mobile-billing-content.tsx:254`).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+Never. Treat this folder as source to delete, or as the place to land the fix if the
+team decides the shipped row should regain `onClick` and a props spread — the two
+capabilities this copy has and the shipped one lacks.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A mobile credit-usage row | `UsageHistoryMobile` (`src/SC-UsageHistoryMobile/`) |
+| A mobile invoice row | `InvoiceHistoryMobile` (`src/SC-InvoiceHistoryMobile/`) |
+| Desktop credit/usage log table | `ScBillingLogsTableHeader` + `ScBillingLogsTableList` |
+| A clickable mobile row with DS-provided semantics | `ScTableListMobile` (`onRowClick`) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `UsageHistoryMobile` — the exported row; `serviceName`/`credits`/`balance`, no `onClick` | This one is unexported and uses `title`/`usageCount`/`totalCount` |
+| `ScInvoiceHistoryMobile` — the *other* unexported duplicate, for invoice rows | Same situation, different data |
+| `InvoiceHistoryMobile` — the exported invoice row | One text column, green amount |
+
+The library contains **two** unexported `Sc*`-prefixed duplicates —
+`ScUsageHistoryMobile` and `ScInvoiceHistoryMobile` — while the exported pair
+(`UsageHistoryMobile`, `InvoiceHistoryMobile`) are the only two components in the
+**mobile** family without an `Sc` prefix. (The package has other un-prefixed exports —
+`CreditWarningBanner`, `StreamoidSidebar`, `NscWorkspaceSwitch` — but none of them are
+mobile.) That inversion is the easiest naming mistake to make in this family.
+
+---
+
+## 4. Why to use it
+
+There is no reason to. What the shipped twin gives you that this does not: it is
+actually in the bundle. What this gives you that the shipped twin does not: `onClick`
+and a props spread — both reproducible today with a wrapper `div`.
+
+---
+
+## Gotchas
+
+**1. It is not importable.** `src/index.ts` exports
+`./SC-UsageHistoryMobile/UsageHistoryMobile` and nothing from
+`./SC-UsageHistory-Mobile/`. The two folder names differ only by a hyphen.
+
+**2. Its CSS is not in the shipped stylesheet.** Nothing imports the module, so esbuild
+never sees `ScUsageHistoryMobile.module.css`. Even a deep import from source would
+render **unstyled** in a consumer repo.
+
+**3. Three renamed props.** Copying an old snippet across leaves `title`,
+`usageCount` and `totalCount` unrecognised, so the shipped component silently falls
+back to its demo defaults (`"Artifax Generation"`, `"50"`, `"84,902"`) — a row of
+believable wrong numbers rather than an error.
+
+**4. `className` is concatenated unguarded** here, emitting a literal `undefined`
+class. The shipped twin guards with `?? ""`.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+To be precise: it cannot have one — it is not exported, so no host *could* render it.
+It is not agent-runtime either; it is dead source. The surface it was drawn for uses
+the exported twin at
+`cxo-dashboard/src/app/components/mobile-billing-content.tsx:254`.
+
+---
+
+## Related
+
+- `UsageHistoryMobile` — **use this**; the shipped mobile usage row.
+- `InvoiceHistoryMobile` — the shipped mobile invoice row.
+- `ScInvoiceHistoryMobile` — the other unexported duplicate, same story.
+- `ScBillingLogsTableHeader` / `ScBillingLogsTableList` — the desktop table.

package/dist/docs/ScVDivider.md

@@ -0,0 +1,215 @@
+---
+component: ScVDivider
+package: "@streamoid/ui"
+category: layout
+status: stable
+renders: div
+tags: [divider, separator, vertical, hairline, rule, column-separator, pipe]
+related: [ScHDivider]
+do_not_confuse_with: [ScHDivider]
+used_by: [cxo, catalogix, artifax]
+---
+
+# ScVDivider
+
+**The vertical hairline.** A zero-width `<div>` whose entire visible body is a
+`border-left: 0.5px solid var(--alias-border-divider)`, stretched to the height of
+its flex-row parent. Unlike its horizontal sibling it accepts a `color` override and
+a real `style` prop.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a rule between two things sitting side by side —
+  a search field and a close button, two stat columns, a toolbar's action groups.
+- **Don't reach for it when:** the rule runs horizontally between stacked sections
+  (→ `ScHDivider`).
+- **Three things that will bite you:**
+  1. It only shows up in a **flex-row** parent (it relies on `align-self: stretch`
+     for its height). In a flex-column parent it is invisible.
+  2. It's a **border**, not a background. Setting `width` or `background` does
+     nothing visible; thickness is `border-left-width`.
+  3. `style` is merged **after** `color`, so `style={{ borderLeftColor: … }}`
+     silently wins over the `color` prop.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScVDivider } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<div style={{ display: "flex", alignItems: "center", gap: 12 }}>
+  <Left />
+  <ScVDivider />
+  <Right />
+</div>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `color` | `string` | – | Sets `borderLeftColor` inline. Pass a **token var**, e.g. `"var(--alias-border-default)"`, not a hex. Overridable by `style` — see Gotcha 3. |
+| `className` | `string` | – | Appended after the internal class (guarded, so no stray `"undefined"`). |
+| `style` | `CSSProperties` | – | Merged **on top of** the `color`-derived style. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Properly typed here (unlike `ScHDivider`) — `onClick`, `role`, `aria-*`, `data-*` all compile. |
+
+### What the stylesheet does
+
+| Declaration | Consequence |
+|---|---|
+| `width: 0` + `border-left: 0.5px solid var(--alias-border-divider)` | The line *is* the border. Total footprint ≈ 0.5px. |
+| `align-self: stretch` | Height = the flex-row parent's cross size. No `height` needed. |
+| `flex-shrink: 0` | Won't be crushed out of existence in a tight row. |
+| `box-sizing: border-box` | The border is included in the (zero) box width. |
+
+### Recipes
+
+```tsx
+// Toolbar: separate the search field from the close affordance
+<div style={{ display: "flex", alignItems: "center", gap: 12 }}>
+  <ScOnlyField placeholderFilled="Search..." style={{ width: 256 }} />
+  <ScVDivider color="var(--alias-border-default)" />
+  <SiconClose onClick={onClose} />
+</div>
+
+// Force full-height inside a parent that isn't `align-items: stretch`
+<ScVDivider style={{ alignSelf: "stretch" }} />
+
+// Two stat columns inside a card
+<div className="flex">
+  <Stat label="Used" value={used} />
+  <ScVDivider className="mx-4" />
+  <Stat label="Remaining" value={left} />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **Toolbars / search rows** — CXO's app-switcher separates the search field from
+  the close button with one.
+- **Workspace and profile cards** — `ScWorkspaceCard`, `ScWorkspaceSwitchCard` and
+  `ScProfileImageUpdate` compose it internally to split metadata columns.
+- **Workspace switcher lists** — Catalogix's `LeftMenu/WorkspaceListing` and the DS
+  `StreamoidWorkspaceSwitcher`.
+- **Chat pending-action rows** — `ScPendingAction` uses it as the left rail.
+
+Rendered by CXO, Catalogix and Artifax. Photogenix ships `ScHDivider` but has no
+`ScVDivider` call site yet (its migration list still has it as a TODO).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Two sibling elements share a horizontal row and need a visual break that a `gap`
+  alone doesn't give.
+- You want the rule to auto-size to the row's height instead of guessing a `height`.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Horizontal rule between stacked sections | `ScHDivider` |
+| A full-height border around a panel | the panel's own `border` token |
+| A tall left rail with content in it | your own flex column — this div can hold no children usefully (0 width) |
+| Purely visual breathing room | a `gap`, not a divider |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScHDivider` — horizontal, `height: 0.5px` background fill, **no** `color` prop and an untyped props bag | `ScVDivider` is vertical, border-based, `color`-aware and fully typed |
+
+---
+
+## 4. Why to use it
+
+- **Correct in both themes.** `--alias-border-divider` resolves to `#d2d2d2` in
+  light and a near-black neutral in dark. A hardcoded `#242424` disappears on the
+  light canvas.
+- **Height without arithmetic.** `align-self: stretch` means it always matches its
+  row, so the rule never ends 2px short of the neighbouring text.
+- **Typed props.** Because it extends `HTMLAttributes`, you can add
+  `role="separator"` / `aria-orientation="vertical"` where the separation is
+  meaningful — something `ScHDivider` won't let you type.
+
+---
+
+## Gotchas
+
+**1. Invisible in a flex-column parent.** In a column, `align-self: stretch` would
+stretch its *width* — but the explicit `width: 0` wins — and nothing gives it a height.
+Zero area either way.
+
+```tsx
+// WRONG — renders nothing
+<div style={{ display: "flex", flexDirection: "column" }}>
+  <A /><ScVDivider /><B />
+</div>
+
+// RIGHT
+<div style={{ display: "flex", flexDirection: "column" }}>
+  <A /><ScHDivider /><B />
+</div>
+```
+
+**2. `width` and `background` do nothing.** The line is a left border. To make it
+2px, set `border-left-width`, not `width`.
+
+```tsx
+// WRONG — still 0.5px
+<ScVDivider style={{ width: 2, background: "red" }} />
+
+// RIGHT
+<ScVDivider style={{ borderLeftWidth: 2, borderLeftColor: "var(--alias-border-default)" }} />
+```
+
+**3. `style` beats `color`.** The implementation is
+`style={color ? { borderLeftColor: color, ...style } : style}` — your `style` spreads
+last, so a `borderLeftColor` in `style` overrides the `color` prop. Pick one.
+
+**4. `color` accepts any string, including hex.** Nothing stops you shipping
+`color="#242424"`, which breaks light mode. Pass a token var.
+
+**5. If the parent sets `align-items: center` (or `flex-start`), `align-self:
+stretch` still applies** — but if a *host* class resets `align-self`, the divider
+collapses. Catalogix pins it explicitly with `style={{ alignSelf: "stretch" }}`;
+Artifax uses `className="self-stretch"`. Do the same when the row's alignment is
+not `stretch`-friendly.
+
+**6. It's decorative by default.** No `role`, no `aria-orientation`. Add them
+yourself if the split carries meaning.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/app-switcher.tsx:258
+<ScVDivider color="var(--alias-border-default)" />
+
+// catalogix/dashboard  app/containers/LeftMenu/WorkspaceListing/index.jsx:322
+<ScVDivider style={{ alignSelf: "stretch" }} />
+
+// artifax  packages/shared/src/components/DashboardSidebar.tsx:1111
+<ScVDivider className="self-stretch" />
+```
+
+---
+
+## Related
+
+- `ScHDivider` — the horizontal sibling; no `color` prop, untyped props bag.
+- `ScWorkspaceCard` / `ScWorkspaceSwitchCard` / `ScProfileImageUpdate` /
+  `ScPendingAction` — DS components that already compose one internally.