@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScAskAgentButton.md

@@ -0,0 +1,307 @@
+---
+component: ScAskAgentButton
+also_exports: [ScAskAgentSlot, AssistantCta]
+package: "@streamoid/ui"
+category: sidebar
+status: stable
+renders: button[type="button"]
+tags: [ask-cxo, assistant, agent, cta, gradient, copilot, sidebar-footer, pill]
+related: [StreamoidSidebar, ScArtifaxSidebar, ScButton, ScQuickPrompt]
+do_not_confuse_with: [ScButton, ScCxoCopilotLogo, ScQuickPrompt, ScSidebarMenu]
+used_by: [catalogix, artifax]
+required_props: [cta]
+---
+
+# ScAskAgentButton
+
+**The gradient "Ask CXO" call-to-action that sits just above a sidebar's profile
+row.** A red→coral gradient pill with a leading icon and a label when expanded; a
+40×40 gradient square with only the icon when collapsed. `ScAskAgentSlot` is the same
+button plus the rail insets both sidebars use.
+
+You will normally never render it yourself: pass `assistantCta` to `StreamoidSidebar`
+or `ScArtifaxSidebar` and they render `ScAskAgentSlot` for you.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need the assistant-panel CTA **outside** a DS sidebar.
+  Inside one, use the sidebar's `assistantCta` prop instead.
+- **Don't reach for it when:** it's an ordinary action (→ `ScButton`), a suggested
+  prompt chip in a chat (→ `ScQuickPrompt`), or a nav row (→ `ScSidebarMenu`).
+- **Three things that will bite you:**
+  1. `collapsed` drops the label, so with **no `icon` the collapsed square renders
+     empty** — a 40×40 patch of gradient with nothing in it.
+  2. Colours are **deliberately not tokens**: a hardcoded gradient and `#f5f5f5`
+     text. It looks identical in light and dark mode. That's the design, not a bug.
+  3. There is **no `disabled`** and no `loading`. Every click fires.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import {
+  ScAskAgentButton,
+  ScAskAgentSlot,
+  type AssistantCta,
+} from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+Through a sidebar (the normal path — the sidebar picks the right variant per rail):
+
+```tsx
+<StreamoidSidebar
+  assistantCta={{
+    label: "Ask CXO",
+    icon: <SiconBolt size={20} color="currentColor" />,
+    active: askOpen,
+    onClick: () => setAskOpen((v) => !v),
+  }}
+  /* … */
+/>
+```
+
+Standalone:
+
+```tsx
+<ScAskAgentSlot
+  cta={{ label: "Ask CXO", icon: <SiconBolt size={20} />, onClick: openAssistant }}
+/>
+```
+
+### Props — `ScAskAgentButton` and `ScAskAgentSlot`
+
+Both take exactly the same two props (`IScAskAgentButtonProps`).
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `cta` | `AssistantCta` | — | **Required.** The whole contract lives in this object. |
+| `collapsed` | `boolean` | `false` | `true` → 40×40 icon-only square, label dropped, `flex-shrink: 0`. `false` → full-width pill. |
+
+### `AssistantCta`
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | — | **Required.** Visible text when expanded. When collapsed it is **invisible but still the accessible name** — never drop it. |
+| `icon` | `ReactNode` | – | Leading icon; rendered in both states. ⚠️ Optional in the type, **mandatory in practice for `collapsed`** (it is the only content). |
+| `active` | `boolean` | – | Pressed styling (a 1.5px inset white ring) and `aria-pressed`. Wire it to "the panel this opens is visible". |
+| `ariaLabel` | `string` | falls back to `label` | Used for both `aria-label` and the native `title` tooltip. |
+| `onClick` | `() => void` | — | **Required.** |
+
+### What renders in each state
+
+| | `collapsed={false}` | `collapsed={true}` |
+|---|---|---|
+| Button | `width: 100%`, `padding: var(--spacing-xl)` (12px) | `2.5rem × 2.5rem`, `padding: var(--spacing-md)` |
+| Icon | rendered, svg pinned to 20×20 | rendered, the only content |
+| Label | 12px/600, `nowrap`, `#f5f5f5` | **not rendered** |
+| Slot insets | `padding: 0 8px 16px` (full width) | `padding: 8px 0`, centred |
+| `aria-pressed` | `cta.active ?? undefined` | same |
+
+### Recipes
+
+```tsx
+// Both rails, driven by the sidebar (Catalogix / Artifax)
+<ScArtifaxSidebar
+  expanded={!collapsed}
+  assistantCta={
+    onToggleAssistant
+      ? { label: "Ask CXO", icon: <SiconBolt className="h-5 w-5" />, active: assistantOpen, onClick: onToggleAssistant }
+      : undefined            // omit/null hides the CTA entirely
+  }
+  /* … */
+/>
+
+// Standalone, mirroring the sidebar rails yourself
+{expanded
+  ? <ScAskAgentSlot cta={cta} />
+  : <ScAskAgentSlot cta={cta} collapsed />}
+
+// Bare button (no rail insets) — e.g. in a page header or an empty state
+<ScAskAgentButton
+  cta={{
+    label: "Ask CXO",
+    ariaLabel: "Open the CXO assistant",   // distinct tooltip / accessible name
+    icon: <SiconBolt size={20} />,
+    active: panelOpen,
+    onClick: togglePanel,
+  }}
+/>
+
+// "Disabled" isn't supported — gate at the call site instead
+{canUseAssistant ? <ScAskAgentSlot cta={cta} /> : null}
+```
+
+---
+
+## 2. Where to use it
+
+- **The pre-footer slot of a sidebar rail**, immediately above `preFooterContent` and
+  the profile row. `StreamoidSidebar` renders `<ScAskAgentSlot cta={assistantCta} />`
+  (expanded) / `<ScAskAgentSlot cta={assistantCta} collapsed />` (collapsed);
+  `ScArtifaxSidebar` does the same.
+- **Live hosts:** Catalogix (`LeftMenu`, via `StreamoidSidebar`) and Artifax
+  (`DashboardSidebar`, via `ScArtifaxSidebar`). CXO instead exposes "Ask CXO" as a
+  **top nav item** in its sidebar body, so it does not use this component.
+- Standalone use (bare `ScAskAgentButton`) is fine anywhere the CTA must not be
+  inset for a 256px rail.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The action is **"open the assistant/copilot panel"** and it should read as a
+  special, branded affordance rather than a regular button.
+- You need it to survive rail collapse without a second implementation.
+- You want `aria-pressed` to track whether the panel is open.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Any ordinary action or CTA | `ScButton` (`variant="mono"` / `"primary"` / `"outline"`) |
+| A suggested-prompt chip inside the chat transcript | `ScQuickPrompt` |
+| A nav row that happens to route to the assistant | `ScSidebarMenu`, or `StreamoidSidebar`'s `topItems` — what CXO does |
+| The CXO Copilot brand lockup / logo | `ScCxoCopilotLogo` |
+| A destructive/primary form submit | `ScButton variant="error"` / `"primary"` |
+| You need `disabled`, `loading` or a spinner | `ScButton` — this component has none |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScButton` — six variants, tokenised, `loading`, `state="disabled"` | This is one fixed brand gradient with no states beyond `active` |
+| `ScQuickPrompt` — chat-runtime prompt chips | Different family, different surface |
+| `ScCxoCopilotLogo` — brand art | Not interactive |
+| `ScSidebarMenu` with an icon | The nav-row treatment; no gradient |
+
+---
+
+## 4. Why to use it
+
+- **One gradient, one place.** The CSS was extracted verbatim from
+  `ScArtifaxSidebar.module.css` so Artifax's pill and the CXO/Catalogix pill cannot
+  drift. Matches Figma `SC-AskAgent` (node 6141-7469): red→coral 135° gradient, 0.5px
+  red-tinted stroke, `var(--radius-2xl)` corners (**14px** with `@streamoid/tokens`
+  loaded — the `0.75rem`/12px in the CSS is only the no-token fallback), 12px padding.
+- **Deliberately theme-*in*variant, correctly.** The gradient is always dark, so the
+  label and icon are pinned to `#f5f5f5` rather than `--alias-text-*`. Using the token
+  would make the text black-on-red in light mode. Hand-rolling this is exactly how
+  that bug ships.
+- **Both rails in one prop.** `collapsed` swaps a full-width pill for a 40×40 square
+  and drops the label while keeping the accessible name — no duplicate markup, no
+  divergent hover.
+- **Correct toggle semantics.** Real `<button type="button">` with `aria-pressed`,
+  a `title` tooltip, and a `:focus-visible` ring designed to be visible **on the
+  gradient** (white, 2px, 2px offset).
+- **The slot owns the rail geometry.** `ScAskAgentSlot` carries the Figma insets
+  (8px horizontal, 16px gap before the divider), so a sidebar only decides *whether*
+  to show the CTA.
+
+---
+
+## Gotchas
+
+**1. Collapsed with no `icon` renders an empty gradient square.** The label is
+suppressed and `icon` is optional, so nothing is left.
+
+```tsx
+// WRONG — a blank 40×40 gradient tile
+<ScAskAgentSlot cta={{ label: "Ask CXO", onClick: open }} collapsed />
+
+// RIGHT
+<ScAskAgentSlot cta={{ label: "Ask CXO", icon: <SiconBolt size={20} />, onClick: open }} collapsed />
+```
+
+**2. Don't drop `label` when collapsing.** It is required, and it supplies both
+`aria-label` and `title` when `ariaLabel` is unset — the collapsed square's only
+accessible name.
+
+**3. It ignores your theme.** Gradient `rgba(217,21,54) → rgba(238,94,58)`, border
+`rgba(255,0,0,0.32)`, text/icon `#f5f5f5`, hover `filter: brightness(1.08)` — all
+literal, none tokenised. It will not respond to light mode, `data-theme`, or a
+`color` you set on a parent.
+
+**4. Your icon's colour is not overridden, but the container's is.**
+`.askAgentIcon` sets `color: #f5f5f5`, so an icon drawn with `currentColor`
+(`<SiconBolt color="currentColor" />`) comes out light — which is what you want. An
+icon with an explicit token colour will keep it and may be unreadable on the gradient.
+
+**5. The svg is pinned to 20×20 at class-level specificity.**
+`.askAgentIcon :where(svg) { width: 1.25rem; height: 1.25rem }`. `:where()` adds no
+specificity, so a Tailwind `h-5 w-5` on your icon *ties* and the winner depends on
+stylesheet order. If you need a different size, set it inline:
+`<MyIcon style={{ width: 24, height: 24 }} />`.
+
+**6. No `disabled`, no `loading`, no `state`.** Gate rendering at the call site
+(Artifax only builds the `assistantCta` object when the host supplies a toggle).
+
+**7. `active` is styling *and* semantics.** It adds an inset white ring **and** sets
+`aria-pressed`. Don't use it as a "highlight" for anything other than "the thing this
+opens is currently open", or screen readers will lie.
+
+**8. Don't double it up.** Both sidebars render this from `assistantCta`. Adding your
+own `ScAskAgentSlot` to `preFooterContent` gives you two pills stacked.
+
+**9. `ScAskAgentButton` vs `ScAskAgentSlot`.** The button has **no outer margin**; the
+slot adds the rail insets (`0 8px 16px` expanded, `8px 0` collapsed). Inside a sidebar
+rail use the slot; elsewhere use the button and space it yourself.
+
+**10. The focus ring is white.** `outline: 2px solid rgba(255,255,255,0.9)` — it's
+designed to sit on the gradient. On a white page background the offset ring is
+effectively invisible.
+
+**11. `ArtifaxSidebarAssistantCta` is just an alias of `AssistantCta`.** Kept as a
+named export for back-compat; the same object satisfies both sidebars.
+
+---
+
+## In the wild
+
+The hosts render it through their sidebar's `assistantCta` prop rather than importing
+the component:
+
+```jsx
+// catalogix/dashboard  app/containers/LeftMenu/index.jsx:1005   (→ StreamoidSidebar renders ScAskAgentSlot)
+assistantCta={{
+  label: "Ask CXO",
+  icon: <SiconBolt size={20} color="currentColor" />,
+  active: askCxoOpen,
+  onClick: toggleAskCxo,
+}}
+```
+
+```tsx
+// artifax  packages/shared/src/components/DashboardSidebar.tsx:684   (→ ScArtifaxSidebar renders ScAskAgentSlot)
+assistantCta={
+  onToggleAssistant
+    ? {
+        label: ASK_CXO_LABEL,
+        icon: <SiconBolt className="h-5 w-5" />,
+        active: assistantOpen,
+        onClick: onToggleAssistant,
+      }
+    : undefined
+}
+```
+
+No host imports `ScAskAgentButton` / `ScAskAgentSlot` directly — if you need it
+outside a DS sidebar rail, you are the first, and `ScAskAgentButton` (not the slot)
+is the right entry point.
+
+---
+
+## Related
+
+- `StreamoidSidebar` — pass `assistantCta`; it renders the slot in both rails.
+- `ScArtifaxSidebar` — same, via `ArtifaxSidebarAssistantCta`.
+- `ScButton` — the tokenised, stateful button for everything that isn't this CTA.
+- `ScQuickPrompt` — suggested-prompt chips inside the chat surface.
+- `@streamoid/icons` — `SiconBolt` is the icon both hosts pass.

package/dist/docs/ScBadges.md

@@ -0,0 +1,261 @@
+---
+component: ScBadges
+package: "@streamoid/ui"
+category: overlays
+status: stable
+renders: div
+tags: [badge, chip, status, tag, label, pill, count, success, warning, error, info]
+related: [ScBeacon, ScRole, ScSelectionPill, ScTaxonomyPill, ScProgressBar]
+do_not_confuse_with: [ScBeacon, ScSelectionPill, ScTaxonomyPill, ScRole, ScButton]
+used_by: [cxo, photogenix, artifax]
+---
+
+# ScBadges
+
+**The status chip.** A small rounded box with one line of 12px text, in five
+semantic colours × two skins (`solid` filled, `opaque` outlined). Display-only:
+it takes no click handler, no style, no aria — just `text`, `variant`,
+`styleVariant`, `className`.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need to state a status, a count or a tag next to
+  something — "Revoked", "Active", "1,240 credits", "Needs attention".
+- **Don't reach for it when:** it should be clickable (→ `ScSelectionPill`,
+  `ScTaxonomyPill`, `ScButton`), it's a bare status dot with no text
+  (→ `ScBeacon`), or it's specifically an Admin/Member role (→ `ScRole`).
+- **Four things that will bite you:**
+  1. `...props` is destructured but **never spread**. `onClick`, `style`,
+     `title`, `data-*`, `aria-*` are all dropped *and* are type errors. Wrap it.
+  2. The root is `align-self: stretch` ⚠️ — inside a flex row it grows to the
+     tallest sibling's height instead of hugging its text.
+  3. `text` defaults to `"Badge"`.
+  4. `styleVariant="solid"` + `variant="info"` is the one solid combination that
+     does **not** force white text — a real contrast inconsistency.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScBadges } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScBadges text="Revoked" variant="error" />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `text` | `string` | `"Badge"` | ⚠️ Real default. Plain string only — build the label yourself (`` `${n} credits` ``). |
+| `variant` | `"default"` \| `"success"` \| `"warning"` \| `"error"` \| `"info"` | `"default"` | The semantic role. |
+| `styleVariant` | `"solid"` \| `"opaque"` | `"solid"` | `solid` = filled, `opaque` = 1px semantic border + semantic text on a **transparent** background (`background: unset`). |
+| `className` | `string` | – | Concatenated unconditionally — see Gotcha 5. **The only escape hatch you get.** |
+
+`IScBadgesProps` does **not** extend `HTMLAttributes`, and the component's
+`...props` rest is collected and thrown away. There is no `onClick`, `style`,
+`title`, `size`, `icon` or `onClose`.
+
+### The colour matrix
+
+| `variant` | `styleVariant="solid"` | `styleVariant="opaque"` |
+|---|---|---|
+| `default` | fill `--alias-fill-neutral-neutralactive`, text `…-primary` | border `--alias-border-strong`, text `…-tertiary` |
+| `success` | fill `--alias-fill-success-solidactive`, text **`…-fullwhite`** | border `--alias-border-successplus`, text `…-success` |
+| `warning` | fill `--alias-fill-warning-solidactive`, text **`…-fullwhite`** | border `--alias-border-warningplus`, text `…-warning` |
+| `error` | fill `--alias-fill-error-solidactive`, text **`…-fullwhite`** | border `--alias-border-errorplus`, text `…-error` |
+| `info` | fill `--alias-fill-info-solid`, text `…-primary` ⚠️ | border `--alias-border-infoplus`, text `…-info` |
+
+### Recipes
+
+```tsx
+// Outlined status chip — the most common host choice (quieter in dense lists)
+<ScBadges text={label} variant={statusVariant} styleVariant="opaque" />
+
+// Make it clickable / hoverable — wrap it, you cannot pass onClick
+<span role="button" tabIndex={0} onClick={filterByStatus} style={{ cursor: "pointer" }}>
+  <ScBadges text="Needs attention" variant="warning" styleVariant="opaque" />
+</span>
+
+// Stop it stretching to the row height
+<div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+  <span>Feed status</span>
+  <ScBadges text="Live" variant="success" styleVariant="opaque" className="hug" />
+</div>
+// .hug { align-self: center; }   /* or: flex-shrink:0; align-self:auto */
+
+// Map your domain status onto a variant once, at the boundary
+const VARIANT = { active: "success", pending: "warning", failed: "error", draft: "default" } as const;
+<ScBadges text={STATUS_LABEL[s]} variant={VARIANT[s]} styleVariant="opaque" />
+```
+
+---
+
+## 2. Where to use it
+
+- **Table / list rows** — status column. CXO's token list marks revoked API tokens;
+  Photogenix wraps it as `StatusBadge` / `ConsistencyStatusPill` for render batches.
+- **Card headers** — `ScPlanDetailsCard` (+ its Mobile twin), `ScWorkspaceCard` and
+  `ScProfileOptions` each render one internally; pass their own badge prop rather
+  than nesting your own.
+- **Sidebar footer** — Artifax puts the credits figure in an `opaque` badge beside
+  the workspace name.
+- **Referral / billing tables** — `ScReferralTableList` renders one per row.
+- **Gallery / media tiles** — Photogenix's `RendersGallery`.
+
+Used by CXO, Photogenix and Artifax; Catalogix has app-local status pills. Part of
+the catalog's "universal core".
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The content is a **short, non-interactive fact**: a state, a count, a tag.
+- You want the semantic colour pair (fill/border + text) to be identical to every
+  other status in the product, in both themes.
+- The badge sits **beside** its subject, not on top of it.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The chip is a filter/tab the user clicks | `ScSelectionPill` (+ `ScSelectionPillGroup`) |
+| A node in a taxonomy/hierarchy tree with counts and expand/collapse | `ScTaxonomyPill` |
+| Specifically an Admin / Member role marker | `ScRole` / `ScRoleMobile` |
+| A bare coloured status dot, no text | `ScBeacon` |
+| A removable input token with an ✕ | no DS component — build it app-local; this badge has no close affordance |
+| A progress/quantity meter | `ScProgressBar` |
+| A call to action | `ScButton` |
+| A validation message under a field | `ScTextField`'s helper/error text |
+| A dismissible page-level alert | `CreditWarningBanner` (exported without the `Sc` prefix), or your app's banner |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScBeacon` — a 20px two-ring status **dot**, 4 tones (no `info`), `aria-hidden` | `ScBadges` is the text chip; the two are often used together |
+| `ScSelectionPill` — a real `<button aria-pressed>` for segmented selection | `ScBadges` is a non-interactive `<div>` |
+| `ScTaxonomyPill` — tree node with `pill`/`expand`/`collapse` types | Visually similar, structurally different |
+| `ScRole` — dedicated `admin`/`member` badge | Use it instead of hand-mapping roles onto variants |
+
+---
+
+## 4. Why to use it
+
+- **The semantic pairs are already correct in both themes.** Each `opaque` variant
+  pairs a `--alias-border-*plus` (a very dark tinted border) with the matching
+  `--alias-text-and-icons-*`, and each `solid` variant pairs a `*-solidactive` fill
+  with `fullwhite` text. Hand-rolled chips are the most common place a status colour
+  becomes unreadable when light mode collapses the surfaces.
+- **`fullwhite`, not `primary`, on solid fills.** Solid success/warning/error force
+  `--alias-text-and-icons-fullwhite` — deliberately *not* the theme-flipping primary
+  token, because the fill stays saturated in both themes. Getting that wrong is the
+  classic light-mode "white text on light green" bug.
+- **One vocabulary of five statuses.** Every status in the product resolves to the
+  same five colours, so users learn the palette once.
+- **It's tiny and it composes.** `flex-shrink: 0` and centred content mean it sits
+  cleanly in a table cell, a card header or a flex row without pushing anything
+  around — and five DS cards already embed one.
+
+---
+
+## Gotchas
+
+**1. `...props` is collected and never spread.** Look at the source: the rest
+element exists but the returned `<div>` receives only `className`. So there is *no*
+way to attach a handler, an inline style, a tooltip or a test id — and because the
+interface doesn't extend `HTMLAttributes`, TypeScript rejects them anyway.
+
+```tsx
+// WRONG — type error, and nothing happens at runtime either
+<ScBadges text="Revoked" variant="error" onClick={undo} title="Revoked 2 days ago" />
+
+// RIGHT — wrap it
+<span title="Revoked 2 days ago" onClick={undo} role="button" tabIndex={0}>
+  <ScBadges text="Revoked" variant="error" />
+</span>
+```
+
+**2. `align-self: stretch` on the root.** This is the surprise that produces
+"why is my badge tall?". In a flex **row** it stretches to the tallest sibling; in a
+flex **column** it stretches to full width.
+
+```tsx
+// WRONG — badge grows to the height of the two-line name block beside it
+<div style={{ display: "flex" }}>
+  <div><b>{name}</b><br />{email}</div>
+  <ScBadges text="Admin" />
+</div>
+
+// RIGHT — pin it, or give the parent alignItems
+<div style={{ display: "flex", alignItems: "center" }}>…</div>
+```
+
+**3. `text` defaults to `"Badge"`.** Forget the prop and you ship the placeholder.
+
+**4. Solid `info` keeps primary text.** Solid success/warning/error force
+`fullwhite`; `info` does not — it renders `--alias-text-and-icons-primary` on a
+`--alias-fill-info-solid` blue, which in light mode is dark-on-blue. Prefer
+`styleVariant="opaque"` for `info`.
+
+**5. `className` is concatenated unconditionally.** Omit it and the class attribute
+contains the literal string `undefined`. Harmless in the browser, breaks
+exact-match snapshots.
+
+**6. `opaque` has `background: unset`.** The chip is transparent, so it inherits
+whatever is behind it — over a busy or coloured surface the text can lose contrast.
+`solid` is the safer choice on non-flat backgrounds.
+
+**7. No `size`, no `icon`, no `onClose`.** Text is always 12px/1.125rem, padding
+always `4px 8px`, radius always `--radius-md`. A leading dot must be a separate
+`ScBeacon` next to it; a removable token is not this component.
+
+**8. `text` is `string`, not `ReactNode`.** You cannot put a `<b>` or an icon
+inside. Interpolate the string.
+
+**9. Five DS cards already render one.** `ScPlanDetailsCard`,
+`ScPlanDetailsCardMobile`, `ScWorkspaceCard`, `ScProfileOptions` and
+`ScReferralTableList` embed a badge internally. Pass their badge/status prop instead
+of nesting a second one.
+
+---
+
+## In the wild
+
+```tsx
+// photogenix_v2  dashboard/client/src/components/studio/StatusBadge.tsx:95
+<ScBadges
+  text={label}
+  variant={getStatusVariant(status)}
+  styleVariant="opaque"
+  className={className}
+/>
+```
+
+```tsx
+// artifax  packages/shared/src/components/DashboardSidebar.tsx:901
+<ScBadges
+  text={creditsLabel}
+  variant={typeof credits === 'number' && credits > 0 ? 'success' : 'default'}
+  styleVariant="opaque"
+/>
+```
+
+---
+
+## Related
+
+- `ScBeacon` — the dot-only status marker; pair it with a badge or use it alone in dense tables.
+- `ScRole` / `ScRoleMobile` — the purpose-built Admin/Member badge.
+- `ScSelectionPill` / `ScTaxonomyPill` — the *interactive* chip vocabulary.
+- `ScProgressBar` — when the status is really a quantity.
+- `ScPlanDetailsCard` / `ScWorkspaceCard` / `ScReferralTableList` — DS parents that already render one.