From 49c9b8a818c1d89e49e0bb281d410915aa5000ec Mon Sep 17 00:00:00 2001
From: brsbl <57682038+brsbl@users.noreply.github.com>
Date: Tue, 22 Sep 2026 23:20:09 -0700
Subject: [PATCH 1/4] feat(plugins): move category into the detail byline and
 refresh overview typography

Replace the tinted category pill beside the plugin title with a
category-colored dot and underlined link in the byline that opens the
category shelf in Browse. Hang the author avatar under the plugin icon so
title and byline text share one column, and drop the Marketplace detail
row for BB Official plugins since the byline already names it.

Rework overview prose: 13px summary line, sentence-case subheads, code
chips without vertical padding, and a 65ch reading width.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../plugin/management/PluginCard.tsx          | 48 +++++++++----
 .../management/PluginMarketplaceListing.tsx   | 70 +++++++++++++++----
 .../management/PluginOverviewMarkdown.tsx     | 26 +++++--
 .../plugin/management/plugin-ui.test.tsx      | 10 +--
 .../plugin/management/plugin-ui.tsx           | 38 ----------
 .../app/src/components/tools/PluginDetail.tsx | 43 ++++++------
 .../PluginsAndSkillsDetailStates.stories.tsx  | 14 +++-
 .../views/ToolsView.plugin-detail.test.tsx    | 26 +++++++
 .../ui/resource/detail-sections.tsx           | 64 ++++++++++-------
 9 files changed, 214 insertions(+), 125 deletions(-)

diff --git a/apps/app/src/components/plugin/management/PluginCard.tsx b/apps/app/src/components/plugin/management/PluginCard.tsx
index fd259082026..49938430a67 100644
--- a/apps/app/src/components/plugin/management/PluginCard.tsx
+++ b/apps/app/src/components/plugin/management/PluginCard.tsx
@@ -81,27 +81,45 @@ interface PluginCardAuthorProps {
   >;
 }
 
+function pluginCardAuthorName(entry: PluginCardAuthorProps["entry"]): string {
+  return entry.marketplace === "bb-official"
+    ? "BB Official"
+    : (entry.author?.name ?? entry.publisherLabel);
+}
+
+export function PluginCardAuthorAvatar({ entry }: PluginCardAuthorProps) {
+  return (
+    <PluginAuthorAvatar
+      name={pluginCardAuthorName(entry)}
+      github={pluginAuthorGithub(entry.author)}
+      official={entry.marketplace === "bb-official"}
+      size="detail"
+    />
+  );
+}
+
+export function PluginCardAuthorName({ entry }: PluginCardAuthorProps) {
+  const name = pluginCardAuthorName(entry);
+  return entry.author === null ? (
+    name
+  ) : (
+    <PluginAuthorLink
+      entry={entry}
+      className="pointer-events-auto relative z-10 rounded-sm underline-offset-2 hover:text-foreground hover:underline focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+    >
+      {name}
+    </PluginAuthorLink>
+  );
+}
+
 export function PluginCardAuthor({ entry }: PluginCardAuthorProps) {
-  const name =
-    entry.marketplace === "bb-official"
-      ? "BB Official"
-      : (entry.author?.name ?? entry.publisherLabel);
   return (
     <PluginAuthorByline
-      name={name}
+      name={pluginCardAuthorName(entry)}
       github={pluginAuthorGithub(entry.author)}
       official={entry.marketplace === "bb-official"}
     >
-      {entry.author === null ? (
-        name
-      ) : (
-        <PluginAuthorLink
-          entry={entry}
-          className="pointer-events-auto relative z-10 rounded-sm underline-offset-2 hover:text-foreground hover:underline focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
-        >
-          {name}
-        </PluginAuthorLink>
-      )}
+      <PluginCardAuthorName entry={entry} />
     </PluginAuthorByline>
   );
 }
diff --git a/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx b/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
index 5cfffa7a0f5..904cb2066ad 100644
--- a/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
+++ b/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
@@ -1,4 +1,5 @@
 import { useEffect, useMemo, useState, type ReactNode } from "react";
+import { Link } from "react-router-dom";
 import {
   Carousel,
   CarouselContent,
@@ -17,23 +18,57 @@ import {
 } from "@bb/shared-ui/resource-list";
 import type { PluginCatalogSearchEntry } from "@/hooks/queries/plugin-catalog-queries";
 import { PluginOverviewMarkdown } from "@/components/plugin/management/PluginOverviewMarkdown";
+import { getPluginsRoutePath } from "@/lib/route-paths";
+import { PluginCardAuthorName } from "./PluginCard";
 import {
   CatalogEntryIconChip,
   formatUrlLabel,
-  PluginCategoryLabel,
+  pluginCatalogCategoryMutedAccentStyle,
 } from "./plugin-ui";
 import {
   entriesByMarketplaceAuthor,
   pluginMarketplaceAuthorKey,
 } from "./plugin-marketplace-author";
 
-export function PluginMarketplaceCategoryPill({
+export function PluginMarketplaceByline({
   entry,
 }: {
-  entry: PluginCatalogSearchEntry;
+  entry: Pick<
+    PluginCatalogSearchEntry,
+    "author" | "marketplace" | "publisherLabel" | "category" | "categoryId"
+  >;
 }) {
-  return entry.category === undefined ? null : (
-    <PluginCategoryLabel categoryId={entry.categoryId} label={entry.category} />
+  return (
+    <span className="flex min-w-0 items-center gap-2">
+      <span className="min-w-0 truncate">
+        <PluginCardAuthorName entry={entry} />
+      </span>
+      {entry.category === undefined ? null : (
+        <span className="flex min-w-0 shrink-[100] items-center gap-1.5">
+          <span
+            aria-hidden
+            className="size-1.5 shrink-0 rounded-full"
+            style={pluginCatalogCategoryMutedAccentStyle(entry.categoryId)}
+          />
+          {entry.categoryId === undefined ? (
+            <span className="min-w-0 truncate">{entry.category}</span>
+          ) : (
+            <Link
+              to={{
+                pathname: getPluginsRoutePath(),
+                search: new URLSearchParams({
+                  shelf: `category:${entry.categoryId}`,
+                }).toString(),
+              }}
+              aria-label={`Browse ${entry.category} plugins`}
+              className="min-w-0 truncate rounded-sm underline decoration-border underline-offset-2 hover:text-foreground hover:decoration-current focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+            >
+              {entry.category}
+            </Link>
+          )}
+        </span>
+      )}
+    </span>
   );
 }
 
@@ -63,9 +98,11 @@ export function PluginMarketplaceDetailMetadata({
 }) {
   return (
     <>
-      <PluginDetailMetadataItem label="Marketplace">
-        {entry.marketplaceDisplayName}
-      </PluginDetailMetadataItem>
+      {entry.marketplace === "bb-official" ? null : (
+        <PluginDetailMetadataItem label="Marketplace">
+          {entry.marketplaceDisplayName}
+        </PluginDetailMetadataItem>
+      )}
       {entry.publishedAt === undefined ? null : (
         <PluginDetailMetadataItem label="Listed">
           <time dateTime={entry.publishedAt}>
@@ -193,7 +230,7 @@ function PluginScreenshotGallery({
 export function PluginOverviewLead({ description }: { description: string }) {
   return (
     <p
-      className="text-base leading-relaxed text-foreground"
+      className="text-sm leading-relaxed text-foreground"
       data-plugin-summary=""
     >
       {description}
@@ -209,7 +246,7 @@ export function PluginMarketplaceOverview({
   return (
     <section className="space-y-6" data-resource-detail-section="overview">
       <PluginScreenshotGallery entry={entry} />
-      <div className="space-y-3">
+      <div className="max-w-prose space-y-4">
         <PluginOverviewLead description={entry.description} />
         {entry.overview === undefined ? null : (
           <>
@@ -232,11 +269,14 @@ export function PluginMarketplaceListingSections({
     <>
       <PluginMarketplaceOverview entry={entry} />
       <PluginMarketplaceSource entry={entry} />
-      <ResourceDefinitionSection label="Details">
-        <PluginDetailMetadata>
-          <PluginMarketplaceDetailMetadata entry={entry} />
-        </PluginDetailMetadata>
-      </ResourceDefinitionSection>
+      {entry.marketplace === "bb-official" &&
+      entry.publishedAt === undefined ? null : (
+        <ResourceDefinitionSection label="Details">
+          <PluginDetailMetadata>
+            <PluginMarketplaceDetailMetadata entry={entry} />
+          </PluginDetailMetadata>
+        </ResourceDefinitionSection>
+      )}
     </>
   );
 }
diff --git a/apps/app/src/components/plugin/management/PluginOverviewMarkdown.tsx b/apps/app/src/components/plugin/management/PluginOverviewMarkdown.tsx
index 3c67e16e989..cc804d77861 100644
--- a/apps/app/src/components/plugin/management/PluginOverviewMarkdown.tsx
+++ b/apps/app/src/components/plugin/management/PluginOverviewMarkdown.tsx
@@ -63,7 +63,13 @@ function OverviewHeading({
 }) {
   const Tag = minor ? "h4" : "h3";
   return (
-    <Tag className="mb-1.5 mt-5 text-xs font-semibold uppercase tracking-wide text-subtle-foreground first:mt-0">
+    <Tag
+      className={
+        minor
+          ? "mb-1 mt-4 text-xs font-medium text-foreground first:mt-0"
+          : "mb-1 mt-6 text-sm font-medium text-foreground first:mt-0"
+      }
+    >
       {children}
     </Tag>
   );
@@ -77,7 +83,7 @@ const OVERVIEW_COMPONENTS: Components = {
     </blockquote>
   ),
   code: ({ children }) => (
-    <code className="rounded bg-surface-recessed px-1 py-0.5 font-mono text-xs text-foreground">
+    <code className="rounded-sm bg-surface-recessed px-1 font-mono text-xs text-foreground [box-decoration-break:clone]">
       {children}
     </code>
   ),
@@ -88,15 +94,23 @@ const OVERVIEW_COMPONENTS: Components = {
   h5: ({ children }) => <OverviewHeading minor>{children}</OverviewHeading>,
   h6: ({ children }) => <OverviewHeading minor>{children}</OverviewHeading>,
   hr: () => <hr className="my-4 border-t border-border" />,
-  li: ({ children }) => <li className="mb-1">{children}</li>,
-  ol: ({ children }) => <ol className="mb-2 list-decimal pl-5">{children}</ol>,
-  p: ({ children }) => <p className="mb-2 last:mb-0">{children}</p>,
+  li: ({ children }) => <li className="pl-0.5">{children}</li>,
+  ol: ({ children }) => (
+    <ol className="mb-3 list-decimal space-y-1 pl-4 marker:text-subtle-foreground">
+      {children}
+    </ol>
+  ),
+  p: ({ children }) => <p className="mb-3 last:mb-0">{children}</p>,
   pre: ({ children }) => (
     <pre className="my-2 overflow-x-auto rounded-md border border-border bg-surface-recessed p-3 font-mono text-xs text-foreground">
       {children}
     </pre>
   ),
-  ul: ({ children }) => <ul className="mb-2 list-disc pl-5">{children}</ul>,
+  ul: ({ children }) => (
+    <ul className="mb-3 list-disc space-y-1 pl-4 marker:text-subtle-foreground">
+      {children}
+    </ul>
+  ),
 };
 
 export function PluginOverviewMarkdown({ markdown }: { markdown: string }) {
diff --git a/apps/app/src/components/plugin/management/plugin-ui.test.tsx b/apps/app/src/components/plugin/management/plugin-ui.test.tsx
index 5f0671ec651..59bd58315f3 100644
--- a/apps/app/src/components/plugin/management/plugin-ui.test.tsx
+++ b/apps/app/src/components/plugin/management/plugin-ui.test.tsx
@@ -6,7 +6,7 @@ import { PLUGIN_CATALOG_CATEGORIES } from "@bb/domain";
 import {
   CatalogEntryIcon,
   CatalogEntryIconChip,
-  pluginCatalogCategoryPillStyle,
+  pluginCatalogCategoryMutedAccentStyle,
   pluginInstallCountPresentation,
 } from "./plugin-ui";
 
@@ -94,14 +94,14 @@ it("uses one glyph box for host and marketplace catalog icons", () => {
 
 it("uses theme accents for all built-in categories and neutral unknowns", () => {
   for (const category of PLUGIN_CATALOG_CATEGORIES) {
-    const style = pluginCatalogCategoryPillStyle(category.id);
+    const style = pluginCatalogCategoryMutedAccentStyle(category.id);
     expect(String(style.background)).toContain("color-mix(in oklab");
     expect(String(style.background)).toContain("var(--");
-    expect(String(style.background)).not.toContain("var(--ink) 8%");
+    expect(String(style.background)).not.toContain("var(--ink)");
   }
-  const unknown = pluginCatalogCategoryPillStyle("future-category");
+  const unknown = pluginCatalogCategoryMutedAccentStyle("future-category");
   expect(unknown.background).toBe(
-    "color-mix(in oklch, var(--ink) 8%, var(--canvas))",
+    "color-mix(in oklch, var(--ink) 36%, var(--canvas))",
   );
 });
 
diff --git a/apps/app/src/components/plugin/management/plugin-ui.tsx b/apps/app/src/components/plugin/management/plugin-ui.tsx
index 1a07b4393b5..00612ff413c 100644
--- a/apps/app/src/components/plugin/management/plugin-ui.tsx
+++ b/apps/app/src/components/plugin/management/plugin-ui.tsx
@@ -65,10 +65,6 @@ function accentTint(token: string, percent: number): string {
   return `color-mix(in oklab, var(${token}) ${percent}%, var(--canvas))`;
 }
 
-function accentInk(token: string, percent: number): string {
-  return `color-mix(in oklab, var(${token}) ${percent}%, var(--ink))`;
-}
-
 function pluginCatalogCategoryAccentToken(
   categoryId: string | undefined,
 ): string | undefined {
@@ -77,23 +73,6 @@ function pluginCatalogCategoryAccentToken(
     : PLUGIN_CATEGORY_ACCENT_TOKENS[categoryId];
 }
 
-export function pluginCatalogCategoryPillStyle(
-  categoryId: string | undefined,
-): CSSProperties {
-  const accentToken = pluginCatalogCategoryAccentToken(categoryId);
-  return accentToken === undefined
-    ? {
-        background: neutral(8),
-        borderColor: neutral(16),
-        color: neutral(55),
-      }
-    : {
-        background: accentTint(accentToken, 10),
-        borderColor: accentTint(accentToken, 18),
-        color: accentInk(accentToken, 50),
-      };
-}
-
 export function pluginCatalogCategoryMutedAccentStyle(
   categoryId: string | undefined,
 ): CSSProperties {
@@ -175,23 +154,6 @@ export function CatalogEntryIcon({
   );
 }
 
-export function PluginCategoryLabel({
-  categoryId,
-  label,
-}: {
-  categoryId: string | undefined;
-  label: string;
-}) {
-  return (
-    <span
-      className="inline-block max-w-full rounded border px-1.5 py-1 align-middle text-right text-2xs leading-snug"
-      style={pluginCatalogCategoryPillStyle(categoryId)}
-    >
-      {label}
-    </span>
-  );
-}
-
 export function CatalogEntryIconChip({
   entry,
   className,
diff --git a/apps/app/src/components/tools/PluginDetail.tsx b/apps/app/src/components/tools/PluginDetail.tsx
index 8317689d4d9..bc14accd847 100644
--- a/apps/app/src/components/tools/PluginDetail.tsx
+++ b/apps/app/src/components/tools/PluginDetail.tsx
@@ -1,4 +1,4 @@
-import { PluginCardAuthor } from "@/components/plugin/management/PluginCard";
+import { PluginCardAuthorAvatar } from "@/components/plugin/management/PluginCard";
 import { useSyncExternalStore } from "react";
 import {
   ResourceActionButton,
@@ -36,7 +36,7 @@ import {
 import {
   PluginDetailMetadata,
   PluginDetailMetadataItem,
-  PluginMarketplaceCategoryPill,
+  PluginMarketplaceByline,
   PluginMarketplaceDetailMetadata,
   PluginMarketplaceListingSections,
   PluginMarketplaceOverview,
@@ -140,6 +140,12 @@ function PluginLocalSource({
   );
 }
 
+const OFFICIAL_BYLINE_ENTRY = {
+  author: null,
+  marketplace: "bb-official",
+  publisherLabel: "BB Official",
+} as const;
+
 export function CatalogPluginDetail({
   entry,
   onInstall,
@@ -158,8 +164,8 @@ export function CatalogPluginDetail({
       leading={<CatalogEntryIconChip entry={entry} compact />}
       leadingClassName="size-6"
       title={entry.displayName}
-      titleMeta={<PluginMarketplaceCategoryPill entry={entry} />}
-      metadata={<PluginCardAuthor entry={entry} />}
+      metadataLeading={<PluginCardAuthorAvatar entry={entry} />}
+      metadata={<PluginMarketplaceByline entry={entry} />}
       actions={
         <PluginCatalogInstallControl
           displayName={entry.displayName}
@@ -354,29 +360,26 @@ export function PluginDetail({
       onSelect: () => onDelete(plugin),
     },
   ];
+  const bylineEntry =
+    catalogEntry ??
+    (plugin.provenance === "builtin" ||
+    plugin.catalogMarketplaceName === "bb-official"
+      ? OFFICIAL_BYLINE_ENTRY
+      : undefined);
   return (
     <ResourceDetailPage
       maxWidthClassName="max-w-5xl"
       leading={<PluginLogo plugin={plugin} className="size-4" />}
       title={pluginName}
-      titleMeta={
-        catalogEntry === undefined ? null : (
-          <PluginMarketplaceCategoryPill entry={catalogEntry} />
+      metadataLeading={
+        bylineEntry === undefined ? undefined : (
+          <PluginCardAuthorAvatar entry={bylineEntry} />
         )
       }
       metadata={
-        catalogEntry !== undefined ? (
-          <PluginCardAuthor entry={catalogEntry} />
-        ) : plugin.provenance === "builtin" ||
-          plugin.catalogMarketplaceName === "bb-official" ? (
-          <PluginCardAuthor
-            entry={{
-              author: null,
-              marketplace: "bb-official",
-              publisherLabel: "BB Official",
-            }}
-          />
-        ) : undefined
+        bylineEntry === undefined ? undefined : (
+          <PluginMarketplaceByline entry={bylineEntry} />
+        )
       }
       actions={
         hasConfiguration ? (
@@ -411,7 +414,7 @@ export function PluginDetail({
     >
       <ResourceDetailStack>
         {catalogEntry === undefined ? (
-          <section data-resource-detail-section="overview">
+          <section className="max-w-prose" data-resource-detail-section="overview">
             <PluginOverviewLead
               description={
                 plugin.description ?? "This plugin does not describe itself."
diff --git a/apps/app/src/components/tools/PluginsAndSkillsDetailStates.stories.tsx b/apps/app/src/components/tools/PluginsAndSkillsDetailStates.stories.tsx
index 16ab522fa71..1fdc37f18e6 100644
--- a/apps/app/src/components/tools/PluginsAndSkillsDetailStates.stories.tsx
+++ b/apps/app/src/components/tools/PluginsAndSkillsDetailStates.stories.tsx
@@ -500,7 +500,19 @@ const UNINSTALLED_CATALOG_PLUGIN = {
   icon: "Github",
   iconUrl: null,
   iconTinted: false,
-  category: "Developer tools",
+  categoryId: "code-and-reviews",
+  category: "Code & Reviews",
+  overview: `Review pull requests and triage issues from the thread you are working in.
+
+## What you get
+
+- A pull request panel with checks, reviews, and the diff for the current branch.
+- Issue search that attaches an issue to the thread as context.
+- A \`bb github\` command for agents to open, update, and comment on pull requests.
+
+## How it works
+
+Sign in once with \`gh auth login\`. The plugin reuses your GitHub CLI session and never stores a token of its own.`,
   screenshots: [],
   collections: [],
   source: "builtin:github",
diff --git a/apps/app/src/views/ToolsView.plugin-detail.test.tsx b/apps/app/src/views/ToolsView.plugin-detail.test.tsx
index ea7135afc25..d469d01198d 100644
--- a/apps/app/src/views/ToolsView.plugin-detail.test.tsx
+++ b/apps/app/src/views/ToolsView.plugin-detail.test.tsx
@@ -225,6 +225,32 @@ describe("PluginDetail official catalog lifecycle", () => {
     expect(container.textContent).not.toContain("Last updated");
   });
 
+  it("links the category from the byline and drops the duplicate official marketplace", () => {
+    render(
+      <MemoryRouter>
+        <CatalogPluginDetail
+          entry={{
+            ...GITHUB_CATALOG_ENTRY,
+            categoryId: "code-and-reviews",
+            category: "Code & Reviews",
+          }}
+          onInstall={() => undefined}
+          catalogEntries={[]}
+          onOpenPlugin={() => undefined}
+        />
+      </MemoryRouter>,
+    );
+
+    const link = screen.getByRole("link", {
+      name: "Browse Code & Reviews plugins",
+    });
+    expect(link.getAttribute("href")).toBe(
+      "/plugins?shelf=category%3Acode-and-reviews",
+    );
+    expect(screen.queryByText("Marketplace")).toBeNull();
+    expect(screen.queryByRole("heading", { name: "Details" })).toBeNull();
+  });
+
   it("explains why an incompatible official plugin cannot be installed", () => {
     const incompatibleEntry = {
       ...GITHUB_CATALOG_ENTRY,
diff --git a/packages/shared-ui/src/components/ui/resource/detail-sections.tsx b/packages/shared-ui/src/components/ui/resource/detail-sections.tsx
index 69824d62eed..7d83893e1fe 100644
--- a/packages/shared-ui/src/components/ui/resource/detail-sections.tsx
+++ b/packages/shared-ui/src/components/ui/resource/detail-sections.tsx
@@ -71,6 +71,7 @@ export function ResourceDetailPage({
   overflowMenu,
   actions,
   metadata,
+  metadataLeading,
   maxWidthClassName = "max-w-3xl",
   children,
 }: {
@@ -82,39 +83,52 @@ export function ResourceDetailPage({
   overflowMenu?: ReactNode;
   actions?: ReactNode;
   metadata?: ReactNode;
+  metadataLeading?: ReactNode;
   maxWidthClassName?: string;
   children: ReactNode;
 }) {
+  const leadingNode = leading ? (
+    <span
+      className={cn(
+        "flex h-6 w-4 shrink-0 items-center justify-center",
+        leadingClassName,
+      )}
+    >
+      {leading}
+    </span>
+  ) : null;
+  const titleRow = (
+    <div className="flex min-w-0 flex-1 flex-wrap items-center gap-x-2 gap-y-1">
+      <h1 className="min-w-0 truncate text-base font-semibold">{title}</h1>
+      {titleMeta ? (
+        <span className="min-w-0 truncate text-xs font-normal text-muted-foreground">
+          {titleMeta}
+        </span>
+      ) : null}
+    </div>
+  );
+  const metadataNode = metadata ? (
+    <div className="min-w-0 text-xs text-subtle-foreground">{metadata}</div>
+  ) : null;
   return (
     <div className={cn("mx-auto w-full space-y-6", maxWidthClassName)}>
       <div className="flex min-w-0 items-start justify-between gap-4">
-        <div className="flex min-w-0 flex-1 items-start gap-x-2">
-          {leading ? (
-            <span
-              className={cn(
-                "flex h-6 w-4 shrink-0 items-center justify-center",
-                leadingClassName,
-              )}
-            >
-              {leading}
-            </span>
-          ) : null}
-          <div className="min-w-0 flex-1 space-y-2">
-            <div className="flex min-w-0 flex-1 flex-wrap items-center gap-x-2 gap-y-1">
-              <h1 className="min-w-0 truncate text-base font-semibold">
-                {title}
-              </h1>
-              {titleMeta ? (
-                <span className="min-w-0 truncate text-xs font-normal text-muted-foreground">
-                  {titleMeta}
-                </span>
-              ) : null}
+        {leadingNode && metadataLeading && metadataNode ? (
+          <div className="grid min-w-0 flex-1 grid-cols-[auto_minmax(0,1fr)] items-center gap-x-2 gap-y-2">
+            <span className="flex justify-center">{leadingNode}</span>
+            {titleRow}
+            <span className="flex justify-center">{metadataLeading}</span>
+            {metadataNode}
+          </div>
+        ) : (
+          <div className="flex min-w-0 flex-1 items-start gap-x-2">
+            {leadingNode}
+            <div className="min-w-0 flex-1 space-y-2">
+              {titleRow}
+              {metadataNode}
             </div>
-            {metadata ? (
-              <div className="text-xs text-subtle-foreground">{metadata}</div>
-            ) : null}
           </div>
-        </div>
+        )}
         {actions || lifecycleControl || overflowMenu ? (
           <div className="flex shrink-0 items-center gap-2 pt-0.5">
             {actions}

From f3f8395e83c18e8d245cb07e069ea81b9de7b74b Mon Sep 17 00:00:00 2001
From: brsbl <57682038+brsbl@users.noreply.github.com>
Date: Wed, 23 Sep 2026 07:53:21 -0700
Subject: [PATCH 2/4] feat(plugins): mark categories with per-category icons
 instead of dots

Replace the category color dot in Browse section headers, the category
shelf title, and the detail byline with a per-category outline icon in
the category color. Solid dots in the success/attention/warning colors
read as bb's machine status dots; icons do not, and they tell categories
apart where several share a color. Unknown and uncategorized categories
show no icon, and the byline omits them.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../plugin/management/BrowsePluginsTab.tsx    | 17 ++----
 .../management/PluginMarketplaceListing.tsx   | 42 ++++++--------
 .../plugin/management/plugin-ui.test.tsx      | 18 +++---
 .../plugin/management/plugin-ui.tsx           | 55 +++++++++++++++----
 .../views/ToolsView.plugin-detail.test.tsx    |  4 +-
 5 files changed, 76 insertions(+), 60 deletions(-)

diff --git a/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx b/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx
index a66880e489b..86cc5a4ea1a 100644
--- a/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx
+++ b/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx
@@ -34,7 +34,7 @@ import {
   sortPluginEntries,
   type PluginBrowseShelf,
 } from "./plugin-browse-discovery";
-import { pluginCatalogCategoryMutedAccentStyle } from "./plugin-ui";
+import { PluginCategoryIcon } from "./plugin-ui";
 
 const SHELF_ENTRY_LIMIT = 6;
 
@@ -215,12 +215,9 @@ export function BrowsePluginsTab({
               <h1 className="flex flex-wrap items-center gap-2 text-xl font-semibold text-foreground">
                 <span className="inline-flex min-w-0 items-center gap-2">
                   {selectedShelf.key.startsWith("category:") ? (
-                    <span
-                      className="size-2 shrink-0 rounded-full"
-                      style={pluginCatalogCategoryMutedAccentStyle(
-                        selectedShelf.categoryId,
-                      )}
-                      aria-hidden
+                    <PluginCategoryIcon
+                      categoryId={selectedShelf.categoryId}
+                      className="size-5"
                     />
                   ) : null}
                   {selectedShelf.label}
@@ -362,11 +359,7 @@ function BrowseShelf({
         ) : shelf.key === "collection:new-and-notable" ? (
           <Icon name="News01" className="size-4 text-foreground" aria-hidden />
         ) : (
-          <span
-            className="size-2 rounded-full"
-            style={pluginCatalogCategoryMutedAccentStyle(shelf.categoryId)}
-            aria-hidden
-          />
+          <PluginCategoryIcon categoryId={shelf.categoryId} className="size-4" />
         )
       }
       browseAction={
diff --git a/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx b/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
index 904cb2066ad..12c00bd6dc8 100644
--- a/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
+++ b/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
@@ -23,7 +23,8 @@ import { PluginCardAuthorName } from "./PluginCard";
 import {
   CatalogEntryIconChip,
   formatUrlLabel,
-  pluginCatalogCategoryMutedAccentStyle,
+  pluginCatalogCategoryIconName,
+  PluginCategoryIcon,
 } from "./plugin-ui";
 import {
   entriesByMarketplaceAuthor,
@@ -43,29 +44,22 @@ export function PluginMarketplaceByline({
       <span className="min-w-0 truncate">
         <PluginCardAuthorName entry={entry} />
       </span>
-      {entry.category === undefined ? null : (
-        <span className="flex min-w-0 shrink-[100] items-center gap-1.5">
-          <span
-            aria-hidden
-            className="size-1.5 shrink-0 rounded-full"
-            style={pluginCatalogCategoryMutedAccentStyle(entry.categoryId)}
-          />
-          {entry.categoryId === undefined ? (
-            <span className="min-w-0 truncate">{entry.category}</span>
-          ) : (
-            <Link
-              to={{
-                pathname: getPluginsRoutePath(),
-                search: new URLSearchParams({
-                  shelf: `category:${entry.categoryId}`,
-                }).toString(),
-              }}
-              aria-label={`Browse ${entry.category} plugins`}
-              className="min-w-0 truncate rounded-sm underline decoration-border underline-offset-2 hover:text-foreground hover:decoration-current focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
-            >
-              {entry.category}
-            </Link>
-          )}
+      {entry.category === undefined ||
+      pluginCatalogCategoryIconName(entry.categoryId) === undefined ? null : (
+        <span className="flex min-w-0 shrink-[100] items-center gap-1">
+          <PluginCategoryIcon categoryId={entry.categoryId} className="size-3" />
+          <Link
+            to={{
+              pathname: getPluginsRoutePath(),
+              search: new URLSearchParams({
+                shelf: `category:${entry.categoryId}`,
+              }).toString(),
+            }}
+            aria-label={`Browse ${entry.category} plugins`}
+            className="min-w-0 truncate rounded-sm underline decoration-border underline-offset-2 hover:text-foreground hover:decoration-current focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+          >
+            {entry.category}
+          </Link>
         </span>
       )}
     </span>
diff --git a/apps/app/src/components/plugin/management/plugin-ui.test.tsx b/apps/app/src/components/plugin/management/plugin-ui.test.tsx
index 59bd58315f3..af6295e828f 100644
--- a/apps/app/src/components/plugin/management/plugin-ui.test.tsx
+++ b/apps/app/src/components/plugin/management/plugin-ui.test.tsx
@@ -6,7 +6,7 @@ import { PLUGIN_CATALOG_CATEGORIES } from "@bb/domain";
 import {
   CatalogEntryIcon,
   CatalogEntryIconChip,
-  pluginCatalogCategoryMutedAccentStyle,
+  pluginCatalogCategoryIconName,
   pluginInstallCountPresentation,
 } from "./plugin-ui";
 
@@ -92,17 +92,13 @@ it("uses one glyph box for host and marketplace catalog icons", () => {
   }
 });
 
-it("uses theme accents for all built-in categories and neutral unknowns", () => {
-  for (const category of PLUGIN_CATALOG_CATEGORIES) {
-    const style = pluginCatalogCategoryMutedAccentStyle(category.id);
-    expect(String(style.background)).toContain("color-mix(in oklab");
-    expect(String(style.background)).toContain("var(--");
-    expect(String(style.background)).not.toContain("var(--ink)");
-  }
-  const unknown = pluginCatalogCategoryMutedAccentStyle("future-category");
-  expect(unknown.background).toBe(
-    "color-mix(in oklch, var(--ink) 36%, var(--canvas))",
+it("gives every built-in category its own icon and unknowns none", () => {
+  const icons = PLUGIN_CATALOG_CATEGORIES.map((category) =>
+    pluginCatalogCategoryIconName(category.id),
   );
+  expect(icons).not.toContain(undefined);
+  expect(new Set(icons).size).toBe(icons.length);
+  expect(pluginCatalogCategoryIconName("future-category")).toBeUndefined();
 });
 
 it("labels install counts only when the catalog knows them", () => {
diff --git a/apps/app/src/components/plugin/management/plugin-ui.tsx b/apps/app/src/components/plugin/management/plugin-ui.tsx
index 00612ff413c..03a3e80e66c 100644
--- a/apps/app/src/components/plugin/management/plugin-ui.tsx
+++ b/apps/app/src/components/plugin/management/plugin-ui.tsx
@@ -1,5 +1,5 @@
 import { PluginBrandIcon } from "@bb/shared-ui/plugin-icon";
-import { useState, type CSSProperties, type ReactNode } from "react";
+import { useState, type ReactNode } from "react";
 import { Icon } from "@bb/shared-ui/icon";
 import { cn } from "@bb/shared-ui/lib/utils";
 import { ResourceIconFrame } from "@bb/shared-ui/resource-list";
@@ -61,10 +61,6 @@ function neutral(percent: number): string {
   return `color-mix(in oklch, var(--ink) ${percent}%, var(--canvas))`;
 }
 
-function accentTint(token: string, percent: number): string {
-  return `color-mix(in oklab, var(${token}) ${percent}%, var(--canvas))`;
-}
-
 function pluginCatalogCategoryAccentToken(
   categoryId: string | undefined,
 ): string | undefined {
@@ -73,14 +69,51 @@ function pluginCatalogCategoryAccentToken(
     : PLUGIN_CATEGORY_ACCENT_TOKENS[categoryId];
 }
 
-export function pluginCatalogCategoryMutedAccentStyle(
+const PLUGIN_CATEGORY_ICONS: Record<string, string> = {
+  "themes-and-appearance": "Palette",
+  "thread-management": "ListView",
+  "thread-content": "MessageSquare",
+  "memory-and-context": "Brain",
+  security: "Lock",
+  "agents-and-providers": "Bot",
+  environments: "Laptop",
+  "token-usage-and-limits": "ChartColumn",
+  notifications: "BellDot",
+  "code-and-reviews": "GitPullRequest",
+  "file-viewers-and-editors": "FileText",
+  "cloud-and-remote": "Cloud",
+  "command-line": "Terminal",
+  utilities: "Toolbox",
+  "plugin-development": "Puzzle",
+  "tasks-and-workflows": "Workflow",
+};
+
+export function pluginCatalogCategoryIconName(
   categoryId: string | undefined,
-): CSSProperties {
+): string | undefined {
+  return categoryId === undefined ? undefined : PLUGIN_CATEGORY_ICONS[categoryId];
+}
+
+export function PluginCategoryIcon({
+  categoryId,
+  className,
+}: {
+  categoryId: string | undefined;
+  className?: string;
+}) {
+  const iconName = pluginCatalogCategoryIconName(categoryId);
   const accentToken = pluginCatalogCategoryAccentToken(categoryId);
-  return {
-    background:
-      accentToken === undefined ? neutral(36) : accentTint(accentToken, 55),
-  };
+  if (iconName === undefined || accentToken === undefined) return null;
+  return (
+    <Icon
+      name={iconName}
+      className={cn("shrink-0", className)}
+      style={{
+        color: `color-mix(in oklab, var(${accentToken}) 75%, var(--ink))`,
+      }}
+      aria-hidden
+    />
+  );
 }
 
 export function PluginLogo({
diff --git a/apps/app/src/views/ToolsView.plugin-detail.test.tsx b/apps/app/src/views/ToolsView.plugin-detail.test.tsx
index d469d01198d..f63a008a440 100644
--- a/apps/app/src/views/ToolsView.plugin-detail.test.tsx
+++ b/apps/app/src/views/ToolsView.plugin-detail.test.tsx
@@ -168,7 +168,7 @@ describe("PluginDetail official catalog lifecycle", () => {
 
     expect(screen.getByRole("heading", { name: "GitHub" })).toBeTruthy();
     expect(screen.getAllByText("BB Official").length).toBeGreaterThan(0);
-    expect(screen.getByText("Developer tools")).toBeTruthy();
+    expect(screen.queryByText("Developer tools")).toBeNull();
     expect(
       screen.getByText("Browse GitHub issues and pull requests in BB."),
     ).toBeTruthy();
@@ -312,7 +312,7 @@ describe("PluginDetail official catalog lifecycle", () => {
     );
 
     expect(screen.getAllByText("BB Official").length).toBeGreaterThan(0);
-    expect(screen.getByText("Developer tools")).toBeTruthy();
+    expect(screen.queryByText("Developer tools")).toBeNull();
     expect(
       screen.queryByRole("button", { name: "Uninstall GitHub" }),
     ).toBeNull();

From 5feafbf98f1ae4f25e26c5cd9c3f1e4bdbf78477 Mon Sep 17 00:00:00 2001
From: brsbl <57682038+brsbl@users.noreply.github.com>
Date: Wed, 23 Sep 2026 08:00:50 -0700
Subject: [PATCH 3/4] feat(plugins): draw category icons on a tinted tile

Put each category icon on a soft tile in its category color, with the
glyph mixed toward the text color. The tile stays readable at the 12px
byline size and gives Browse section headers a clearer anchor than a
bare outline. PluginCategoryIcon now takes a named size (sm, md, lg) so
the tile and glyph scale together.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../plugin/management/BrowsePluginsTab.tsx    |  4 +--
 .../management/PluginMarketplaceListing.tsx   |  2 +-
 .../plugin/management/plugin-ui.tsx           | 28 ++++++++++++++-----
 3 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx b/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx
index 86cc5a4ea1a..f4d3a4c87a0 100644
--- a/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx
+++ b/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx
@@ -217,7 +217,7 @@ export function BrowsePluginsTab({
                   {selectedShelf.key.startsWith("category:") ? (
                     <PluginCategoryIcon
                       categoryId={selectedShelf.categoryId}
-                      className="size-5"
+                      size="lg"
                     />
                   ) : null}
                   {selectedShelf.label}
@@ -359,7 +359,7 @@ function BrowseShelf({
         ) : shelf.key === "collection:new-and-notable" ? (
           <Icon name="News01" className="size-4 text-foreground" aria-hidden />
         ) : (
-          <PluginCategoryIcon categoryId={shelf.categoryId} className="size-4" />
+          <PluginCategoryIcon categoryId={shelf.categoryId} size="md" />
         )
       }
       browseAction={
diff --git a/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx b/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
index 12c00bd6dc8..6916f6fb780 100644
--- a/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
+++ b/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
@@ -47,7 +47,7 @@ export function PluginMarketplaceByline({
       {entry.category === undefined ||
       pluginCatalogCategoryIconName(entry.categoryId) === undefined ? null : (
         <span className="flex min-w-0 shrink-[100] items-center gap-1">
-          <PluginCategoryIcon categoryId={entry.categoryId} className="size-3" />
+          <PluginCategoryIcon categoryId={entry.categoryId} size="sm" />
           <Link
             to={{
               pathname: getPluginsRoutePath(),
diff --git a/apps/app/src/components/plugin/management/plugin-ui.tsx b/apps/app/src/components/plugin/management/plugin-ui.tsx
index 03a3e80e66c..a06d32d8d05 100644
--- a/apps/app/src/components/plugin/management/plugin-ui.tsx
+++ b/apps/app/src/components/plugin/management/plugin-ui.tsx
@@ -94,25 +94,39 @@ export function pluginCatalogCategoryIconName(
   return categoryId === undefined ? undefined : PLUGIN_CATEGORY_ICONS[categoryId];
 }
 
+const PLUGIN_CATEGORY_ICON_SIZES = {
+  sm: { tile: "size-4", glyph: "size-2.5" },
+  md: { tile: "size-5", glyph: "size-3.5" },
+  lg: { tile: "size-6", glyph: "size-4" },
+} as const;
+
 export function PluginCategoryIcon({
   categoryId,
-  className,
+  size,
 }: {
   categoryId: string | undefined;
-  className?: string;
+  size: keyof typeof PLUGIN_CATEGORY_ICON_SIZES;
 }) {
   const iconName = pluginCatalogCategoryIconName(categoryId);
   const accentToken = pluginCatalogCategoryAccentToken(categoryId);
   if (iconName === undefined || accentToken === undefined) return null;
+  const sizes = PLUGIN_CATEGORY_ICON_SIZES[size];
   return (
-    <Icon
-      name={iconName}
-      className={cn("shrink-0", className)}
+    <span
+      className={cn("grid shrink-0 place-items-center rounded", sizes.tile)}
       style={{
-        color: `color-mix(in oklab, var(${accentToken}) 75%, var(--ink))`,
+        background: `color-mix(in oklab, var(${accentToken}) 16%, var(--canvas))`,
       }}
       aria-hidden
-    />
+    >
+      <Icon
+        name={iconName}
+        className={sizes.glyph}
+        style={{
+          color: `color-mix(in oklab, var(${accentToken}) 70%, var(--ink))`,
+        }}
+      />
+    </span>
   );
 }
 

From 370328507b5988a75ef1be87efcea922387b6a0f Mon Sep 17 00:00:00 2001
From: brsbl <57682038+brsbl@users.noreply.github.com>
Date: Wed, 23 Sep 2026 08:06:54 -0700
Subject: [PATCH 4/4] Revert "feat(plugins): draw category icons on a tinted
 tile"

Go back to the plain outline icon mixed toward the text color. The
tinted tile read too much like the plugin icon chips beside it.

This reverts commit 5feafbf98.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../plugin/management/BrowsePluginsTab.tsx    |  4 +--
 .../management/PluginMarketplaceListing.tsx   |  2 +-
 .../plugin/management/plugin-ui.tsx           | 28 +++++--------------
 3 files changed, 10 insertions(+), 24 deletions(-)

diff --git a/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx b/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx
index f4d3a4c87a0..86cc5a4ea1a 100644
--- a/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx
+++ b/apps/app/src/components/plugin/management/BrowsePluginsTab.tsx
@@ -217,7 +217,7 @@ export function BrowsePluginsTab({
                   {selectedShelf.key.startsWith("category:") ? (
                     <PluginCategoryIcon
                       categoryId={selectedShelf.categoryId}
-                      size="lg"
+                      className="size-5"
                     />
                   ) : null}
                   {selectedShelf.label}
@@ -359,7 +359,7 @@ function BrowseShelf({
         ) : shelf.key === "collection:new-and-notable" ? (
           <Icon name="News01" className="size-4 text-foreground" aria-hidden />
         ) : (
-          <PluginCategoryIcon categoryId={shelf.categoryId} size="md" />
+          <PluginCategoryIcon categoryId={shelf.categoryId} className="size-4" />
         )
       }
       browseAction={
diff --git a/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx b/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
index 6916f6fb780..12c00bd6dc8 100644
--- a/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
+++ b/apps/app/src/components/plugin/management/PluginMarketplaceListing.tsx
@@ -47,7 +47,7 @@ export function PluginMarketplaceByline({
       {entry.category === undefined ||
       pluginCatalogCategoryIconName(entry.categoryId) === undefined ? null : (
         <span className="flex min-w-0 shrink-[100] items-center gap-1">
-          <PluginCategoryIcon categoryId={entry.categoryId} size="sm" />
+          <PluginCategoryIcon categoryId={entry.categoryId} className="size-3" />
           <Link
             to={{
               pathname: getPluginsRoutePath(),
diff --git a/apps/app/src/components/plugin/management/plugin-ui.tsx b/apps/app/src/components/plugin/management/plugin-ui.tsx
index a06d32d8d05..03a3e80e66c 100644
--- a/apps/app/src/components/plugin/management/plugin-ui.tsx
+++ b/apps/app/src/components/plugin/management/plugin-ui.tsx
@@ -94,39 +94,25 @@ export function pluginCatalogCategoryIconName(
   return categoryId === undefined ? undefined : PLUGIN_CATEGORY_ICONS[categoryId];
 }
 
-const PLUGIN_CATEGORY_ICON_SIZES = {
-  sm: { tile: "size-4", glyph: "size-2.5" },
-  md: { tile: "size-5", glyph: "size-3.5" },
-  lg: { tile: "size-6", glyph: "size-4" },
-} as const;
-
 export function PluginCategoryIcon({
   categoryId,
-  size,
+  className,
 }: {
   categoryId: string | undefined;
-  size: keyof typeof PLUGIN_CATEGORY_ICON_SIZES;
+  className?: string;
 }) {
   const iconName = pluginCatalogCategoryIconName(categoryId);
   const accentToken = pluginCatalogCategoryAccentToken(categoryId);
   if (iconName === undefined || accentToken === undefined) return null;
-  const sizes = PLUGIN_CATEGORY_ICON_SIZES[size];
   return (
-    <span
-      className={cn("grid shrink-0 place-items-center rounded", sizes.tile)}
+    <Icon
+      name={iconName}
+      className={cn("shrink-0", className)}
       style={{
-        background: `color-mix(in oklab, var(${accentToken}) 16%, var(--canvas))`,
+        color: `color-mix(in oklab, var(${accentToken}) 75%, var(--ink))`,
       }}
       aria-hidden
-    >
-      <Icon
-        name={iconName}
-        className={sizes.glyph}
-        style={{
-          color: `color-mix(in oklab, var(${accentToken}) 70%, var(--ink))`,
-        }}
-      />
-    </span>
+    />
   );
 }