@sentry/junior-dashboard 0.263.0 → 0.265.0

package/src/client/components/FilterBar.tsx

@@ -3,6 +3,7 @@ import type { ReactNode } from "react";
 import { cn } from "../styles";
 import { Card } from "./layout/Card";
 import { SearchInput } from "./SearchInput";
+import { Tabs, TabsList, TabsTrigger } from "./ui/tabs";
 
 /** Lay out labeled filter groups and an optional search field. */
 export function FilterBar(props: {
@@ -69,43 +70,27 @@ export function FilterTabList(props: {
   value: string;
 }) {
   return (
-    <div
-      aria-label={props.ariaLabel}
-      className="grid min-w-0 grid-cols-3 gap-1 border-b border-dashboard-border-subtle sm:flex sm:overflow-x-auto"
-      role="tablist"
-    >
-      {props.items.map((item) => {
-        const selected = props.value === item.value;
-        return (
-          <button
-            aria-selected={selected}
-            className={cn(
-              "relative flex min-w-0 cursor-pointer items-center justify-between gap-2 border-0 bg-transparent px-3 py-2.5 font-sans font-medium text-xs transition-colors after:absolute after:inset-x-2 after:bottom-0 after:h-px sm:shrink-0 sm:justify-start",
-              selected
-                ? "text-dashboard-accent-text after:bg-dashboard-accent"
-                : "text-dashboard-text-muted after:bg-transparent hover:text-dashboard-text",
-            )}
+    <Tabs onValueChange={props.onChange} value={props.value}>
+      <TabsList
+        aria-label={props.ariaLabel}
+        className="grid grid-cols-3 sm:flex sm:overflow-x-auto"
+        variant="line"
+      >
+        {props.items.map((item) => (
+          <TabsTrigger
+            className="group/tab justify-between sm:shrink-0 sm:justify-start"
             key={item.value || "all"}
-            onClick={() => props.onChange(item.value)}
-            role="tab"
-            type="button"
+            value={item.value}
           >
             {item.label}
             {item.count !== undefined ? (
-              <span
-                className={cn(
-                  "rounded-sm border px-1.5 py-0.5 text-xs",
-                  selected
-                    ? "border-dashboard-accent/20 bg-dashboard-accent/10 text-dashboard-accent-text"
-                    : "border-dashboard-border bg-dashboard-fill-soft text-dashboard-text-muted",
-                )}
-              >
+              <span className="rounded-sm border border-dashboard-border bg-dashboard-fill-soft px-1.5 py-0.5 text-xs text-dashboard-text-muted group-data-active/tab:border-dashboard-accent/20 group-data-active/tab:bg-dashboard-accent/10 group-data-active/tab:text-dashboard-accent-text">
                 {item.count.toLocaleString("en-US")}
               </span>
             ) : null}
-          </button>
-        );
-      })}
-    </div>
+          </TabsTrigger>
+        ))}
+      </TabsList>
+    </Tabs>
   );
 }

package/src/client/components/Metric.tsx

@@ -2,7 +2,7 @@ import type { ReactNode } from "react";
 
 import { cn } from "../styles";
 import { ShimmerText } from "./ShimmerText";
-import { Tooltip } from "./Tooltip";
+import { Tooltip, TooltipContent, TooltipTrigger } from "./ui/tooltip";
 
 export type MetricTooltipLine = {
   label?: string;
@@ -85,34 +85,44 @@ export function MetricValue(props: {
   }
 
   return (
-    <Tooltip
-      align={props.align}
-      className={cn(
-        "w-[calc(100vw-2rem)] max-w-80 rounded-lg border border-dashboard-border-emphasis bg-dashboard-bg text-left text-xs font-normal text-dashboard-text-muted shadow-xl shadow-black/35",
-        props.tooltipCard ? "p-3 leading-snug" : "px-3 py-2 leading-relaxed",
-      )}
-      content={
-        props.tooltipCard ? (
-          <span className="block max-h-[min(30rem,var(--radix-hover-card-content-available-height,30rem))] overflow-y-auto">
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <span
+            className={cn(
+              "inline-flex border-b border-dotted border-dashboard-border-interactive outline-none transition-colors hover:border-dashboard-border-heavy focus-visible:border-dashboard-border-heavy",
+              props.className,
+            )}
+            tabIndex={0}
+          >
+            {props.children}
+          </span>
+        }
+      />
+      <TooltipContent
+        align={
+          props.align === "left"
+            ? "start"
+            : props.align === "right"
+              ? "end"
+              : "center"
+        }
+        className={cn(
+          "w-[calc(100vw-2rem)] max-w-80 rounded-lg bg-dashboard-bg text-left font-normal shadow-xl shadow-black/35",
+          props.tooltipCard ? "p-3 leading-snug" : "px-3 py-2 leading-relaxed",
+        )}
+        side={props.tooltipPlacement === "above" ? "top" : "bottom"}
+      >
+        {props.tooltipCard ? (
+          <span className="block max-h-[min(30rem,var(--available-height,30rem))] overflow-y-auto">
             {props.tooltipCard}
           </span>
         ) : tooltip ? (
           <span className="block max-h-72 overflow-y-auto">
             <TooltipLines lines={tooltip} />
           </span>
-        ) : null
-      }
-      placement={props.tooltipPlacement ?? "below"}
-    >
-      <span
-        className={cn(
-          "inline-flex border-b border-dotted border-dashboard-border-interactive outline-none transition-colors hover:border-dashboard-border-heavy focus-visible:border-dashboard-border-heavy",
-          props.className,
-        )}
-        tabIndex={0}
-      >
-        {props.children}
-      </span>
+        ) : null}
+      </TooltipContent>
     </Tooltip>
   );
 }

package/src/client/components/PageContentSkeleton.tsx

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 
 import { Card } from "./layout/Card";
-import { Skeleton } from "./Skeleton";
+import { Skeleton } from "./ui/skeleton";
 import { cn } from "../styles";
 
 export type PageContentSkeletonVariant =

package/src/client/components/Pagination.tsx

@@ -1,7 +1,7 @@
 import { ChevronLeft, ChevronRight } from "lucide-react";
 
 import { cn } from "../styles";
-import { Button } from "./Button";
+import { Button } from "./ui/button";
 
 /** Render a centered load-more control for cursor or progressive lists. */
 export function LoadMorePagination(props: {

package/src/client/components/ParticipantAvatarStack.tsx

@@ -4,7 +4,7 @@ import { actorLabel } from "../format";
 import { cn } from "../styles";
 import type { Conversation } from "../types";
 import { ActorAvatar } from "./ActorAvatar";
-import { Tooltip } from "./Tooltip";
+import { Tooltip, TooltipContent, TooltipTrigger } from "./ui/tooltip";
 
 const MAX_VISIBLE_PARTICIPANTS = 3;
 
@@ -57,22 +57,25 @@ function Avatar(props: {
 }) {
   const label = participantDescription(props.participant);
   return (
-    <Tooltip
-      content={<ParticipantTooltipContent participant={props.participant} />}
-      focusable
-      triggerClassName="-ml-1 first:ml-0 pointer-events-none [@media(hover:hover)_and_(pointer:fine)]:pointer-events-auto"
-    >
-      <span
-        aria-label={label}
-        className="relative inline-flex rounded-full focus-visible:z-10 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-dashboard-focus"
-        onKeyDown={(event) => event.stopPropagation()}
-        tabIndex={0}
-      >
-        <ActorAvatar
-          name={participantName(props.participant)}
-          size={props.size}
-        />
-      </span>
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <span
+            aria-label={label}
+            className="relative -ml-1 inline-flex rounded-full first:ml-0 pointer-events-none focus-visible:z-10 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-dashboard-focus [@media(hover:hover)_and_(pointer:fine)]:pointer-events-auto"
+            onKeyDown={(event) => event.stopPropagation()}
+            tabIndex={0}
+          >
+            <ActorAvatar
+              name={participantName(props.participant)}
+              size={props.size}
+            />
+          </span>
+        }
+      />
+      <TooltipContent>
+        <ParticipantTooltipContent participant={props.participant} />
+      </TooltipContent>
     </Tooltip>
   );
 }
@@ -105,8 +108,25 @@ export function ParticipantAvatarStack(props: ParticipantAvatarStackProps) {
         />
       ))}
       {hidden.length > 0 ? (
-        <Tooltip
-          content={
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <span
+                aria-label={`${hidden.length} more participants: ${hidden
+                  .map(participantDescription)
+                  .join("; ")}`}
+                className={cn(
+                  "relative -ml-1 inline-grid shrink-0 pointer-events-none [@media(hover:hover)_and_(pointer:fine)]:pointer-events-auto place-items-center rounded-full border-2 border-dashboard-bg bg-dashboard-surface-active font-sans font-semibold tabular-nums leading-none text-dashboard-text-muted focus-visible:z-10 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-dashboard-focus",
+                  props.size === "list" ? "size-6 text-2xs" : "size-7 text-xs",
+                )}
+                onKeyDown={(event) => event.stopPropagation()}
+                tabIndex={0}
+              >
+                +{hidden.length}
+              </span>
+            }
+          />
+          <TooltipContent>
             <span className="grid gap-1 font-sans">
               {hidden.map((participant, index) => (
                 <span key={participantKey(participant, index)}>
@@ -114,23 +134,7 @@ export function ParticipantAvatarStack(props: ParticipantAvatarStackProps) {
                 </span>
               ))}
             </span>
-          }
-          focusable
-          triggerClassName="-ml-1 pointer-events-none [@media(hover:hover)_and_(pointer:fine)]:pointer-events-auto"
-        >
-          <span
-            aria-label={`${hidden.length} more participants: ${hidden
-              .map(participantDescription)
-              .join("; ")}`}
-            className={cn(
-              "relative inline-grid shrink-0 place-items-center rounded-full border-2 border-dashboard-bg bg-dashboard-surface-active font-sans font-semibold tabular-nums leading-none text-dashboard-text-muted focus-visible:z-10 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-dashboard-focus",
-              props.size === "list" ? "size-6 text-2xs" : "size-7 text-xs",
-            )}
-            onKeyDown={(event) => event.stopPropagation()}
-            tabIndex={0}
-          >
-            +{hidden.length}
-          </span>
+          </TooltipContent>
         </Tooltip>
       ) : null}
     </span>

package/src/client/components/ProfileMenu.tsx

@@ -8,12 +8,7 @@ import {
   ShieldCheck,
   UserRound,
 } from "lucide-react";
-import {
-  useEffect,
-  useRef,
-  useState,
-  type PointerEvent as ReactPointerEvent,
-} from "react";
+import { useState } from "react";
 import { Link } from "react-router";
 import type { PersonalSpendReport } from "@sentry/junior/api/schema";
 import type { PluginUserPageLink } from "@sentry/junior-plugin-api";
@@ -23,6 +18,7 @@ import { pluginUserPagePath } from "../pages/user/PluginUserPage";
 import { cn, dashboardInteractiveTextClass } from "../styles";
 import type { Identity } from "../types";
 import { ThemeSwitcher } from "./ThemeSwitcher";
+import { Popover, PopoverContent, PopoverTrigger } from "./ui/popover";
 
 type ProfileMenuProps = {
   identity: Identity;
@@ -65,14 +61,6 @@ export function ProfileMenu({
   variant = "popover",
 }: ProfileMenuProps) {
   const [open, setOpen] = useState(false);
-  const rootRef = useRef<HTMLDivElement>(null);
-  const triggerRef = useRef<HTMLButtonElement>(null);
-  const openTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(
-    undefined,
-  );
-  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(
-    undefined,
-  );
   const email = identity.user.email!;
   const name = identity.user.name?.trim() || email;
   const sevenDaySpend = spend
@@ -85,54 +73,6 @@ export function ProfileMenu({
     (page) => page.navigation === "profile",
   );
 
-  function clearHoverTimers() {
-    if (openTimerRef.current) clearTimeout(openTimerRef.current);
-    if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
-    openTimerRef.current = undefined;
-    closeTimerRef.current = undefined;
-  }
-
-  function openOnHover(event: ReactPointerEvent<HTMLDivElement>) {
-    if (event.pointerType !== "mouse") return;
-    clearHoverTimers();
-    openTimerRef.current = setTimeout(() => setOpen(true), HOVER_OPEN_DELAY_MS);
-  }
-
-  function closeOnHover(event: ReactPointerEvent<HTMLDivElement>) {
-    if (event.pointerType !== "mouse") return;
-    clearHoverTimers();
-    closeTimerRef.current = setTimeout(
-      () => setOpen(false),
-      HOVER_CLOSE_DELAY_MS,
-    );
-  }
-
-  useEffect(() => clearHoverTimers, []);
-
-  useEffect(() => {
-    if (variant !== "popover" || !open) return;
-
-    function closeOnOutsideClick(event: PointerEvent) {
-      if (!rootRef.current?.contains(event.target as Node)) {
-        setOpen(false);
-      }
-    }
-
-    function closeOnEscape(event: KeyboardEvent) {
-      if (event.key === "Escape") {
-        setOpen(false);
-        triggerRef.current?.focus();
-      }
-    }
-
-    document.addEventListener("pointerdown", closeOnOutsideClick);
-    document.addEventListener("keydown", closeOnEscape);
-    return () => {
-      document.removeEventListener("pointerdown", closeOnOutsideClick);
-      document.removeEventListener("keydown", closeOnEscape);
-    };
-  }, [open, variant]);
-
   const avatar = (
     <span
       aria-hidden="true"
@@ -335,32 +275,28 @@ export function ProfileMenu({
   }
 
   return (
-    <div
-      className="relative"
-      onBlurCapture={(event) => {
-        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
-          setOpen(false);
+    <Popover
+      onOpenChange={(nextOpen, details) => {
+        // A mouse click always keeps the menu open, also after hover opened it.
+        // A keyboard press (detail 0) still toggles it.
+        const mouseClick =
+          details.event instanceof MouseEvent && details.event.detail > 0;
+        if (!nextOpen && details.reason === "trigger-press" && mouseClick) {
+          return;
         }
+        setOpen(nextOpen);
       }}
-      onPointerEnter={openOnHover}
-      onPointerLeave={closeOnHover}
-      ref={rootRef}
+      open={open}
     >
-      <button
-        aria-controls="profile-popover"
-        aria-expanded={open}
-        aria-haspopup="true"
+      <PopoverTrigger
         aria-label={`${open ? "Close" : "Open"} profile menu for ${name}. Personal model spend: 7 days ${sevenDaySpend}, 30 days ${thirtyDaySpend}.`}
         className={cn(
           "group flex h-10 cursor-pointer items-center gap-2 rounded-lg border-0 bg-transparent px-1.5 text-dashboard-text transition-colors hover:bg-dashboard-fill-hover hover:text-dashboard-text focus-visible:outline focus-visible:outline-2 focus-visible:outline-dashboard-focus/70",
           open && "bg-dashboard-fill-hover text-dashboard-text",
         )}
-        onClick={(event) => {
-          clearHoverTimers();
-          setOpen(event.detail === 0 ? (value) => !value : true);
-        }}
-        ref={triggerRef}
-        type="button"
+        closeDelay={HOVER_CLOSE_DELAY_MS}
+        delay={HOVER_OPEN_DELAY_MS}
+        openOnHover
       >
         <span className="hidden items-center gap-2 md:flex">
           <span className="flex items-baseline gap-1 whitespace-nowrap tabular-nums">
@@ -399,18 +335,16 @@ export function ProfileMenu({
           size={14}
           strokeWidth={2}
         />
-      </button>
-
-      {open ? (
-        <div
-          className="absolute right-0 top-[calc(100%+0.5rem)] z-40 w-64 rounded-xl bg-dashboard-surface-raised/95 p-1.5 shadow-2xl shadow-black/75 backdrop-blur-xl"
-          id="profile-popover"
-        >
-          {identityBlock}
-          <ThemeSwitcher className="border-b border-dashboard-border-strong px-2.5 py-2" />
-          {menuLinks(() => setOpen(false))}
-        </div>
-      ) : null}
-    </div>
+      </PopoverTrigger>
+      <PopoverContent
+        align="end"
+        className="w-64 rounded-xl border-0 bg-dashboard-surface-raised/95 p-1.5 shadow-2xl shadow-black/75 backdrop-blur-xl"
+        id="profile-popover"
+      >
+        {identityBlock}
+        <ThemeSwitcher className="border-b border-dashboard-border-strong px-2.5 py-2" />
+        {menuLinks(() => setOpen(false))}
+      </PopoverContent>
+    </Popover>
   );
 }

package/src/client/components/README.md

@@ -4,6 +4,74 @@ Shared dashboard components live here. Feature pages compose these surfaces
 instead of copying Tailwind blocks. See `policies/frontend-components.md` for
 the policy. `pnpm dashboard-style:check` enforces the token rules below.
 
+## shadcn/ui
+
+`packages/junior-dashboard/components.json` configures shadcn/ui for this package.
+It uses Base UI (`base-nova`), Tailwind 4, and Lucide. Add components from the
+repository root:
+
+```sh
+pnpm --filter @sentry/junior-dashboard exec shadcn add <component>
+```
+
+The CLI writes components to `src/client/components/ui/`. Its `@dashboard/*`
+alias points to `src/client/*`. The existing `@/*` alias still points to core.
+The `ui/` files join classes with the merging `cn` from
+`src/client/lib/utils.ts`, so a caller's `className` wins over a base class.
+
+The shadcn color tokens in `src/tailwind.css` use the dashboard tokens in both
+themes. The `dark:` variant follows `data-theme`. Keep the existing Tailwind
+radius scale. Do not apply the CLI's global border or body resets. Check each
+added component against the rules below before use.
+
+Each `ui/` file is shadcn source that uses dashboard tokens. Remove exports
+that no app code uses. Use `ui/` components directly. Do not add an app
+component that only renames a `ui/` component or its props. Change the `ui/`
+file when every caller needs the same style or variant. App components compose
+`ui/` source only when they add structure or behavior:
+
+| App component                  | shadcn source     |
+| ------------------------------ | ----------------- |
+| `Drawer`, `BottomSheet`        | `ui/sheet`        |
+| `layout/DashboardHeader` (nav) | `ui/sheet`        |
+| `ProfileMenu` (desktop)        | `ui/popover`      |
+| `TimeRangeSelector`            | `ui/toggle-group` |
+| `ThemeSwitcher`                | `ui/toggle-group` |
+| `TranscriptViewToggle`         | `ui/toggle-group` |
+| `FilterTabList`                | `ui/tabs`         |
+| `charts/ActivityChartTooltip`  | `ui/tooltip`      |
+| `conversations/ToolFrame`      | `ui/trace`        |
+| `TranscriptReasoningView`      | `ui/trace`        |
+| Recharts activity charts       | `ui/chart`        |
+
+Rules for adopted components:
+
+- Use `ui/trace` for transcript activity rows. It composes `ui/collapsible`.
+  A closed tool row unmounts its panel, so it does not run Shiki. Reasoning
+  sets `hiddenUntilFound`, so browser find reaches closed text. Transcript
+  search holds rows open and turns off the row button. Put only inline
+  elements, such as `span`, inside the row button.
+- Use `ui/alert-dialog` for every confirmation. Do not use `window.confirm`.
+  Keep the confirmed item in state after close, so the closing dialog keeps its
+  text.
+- `ui/toast` has no global notification manager. Features call
+  `useToastManager` inside the mounted `Toaster` provider.
+- Put a checkbox or radio inside its `<label>`. Give each `RadioGroup` an
+  `aria-label`.
+- Give an icon-only control its label with `TooltipContent size="compact"`.
+  Do not use the native `title` attribute. Tooltips open on mouse hover and
+  keyboard focus only, so a tap still runs the control.
+- When a `ui/button` tooltip trigger can be disabled, set
+  `focusableWhenDisabled`. A native disabled button can drop hover and focus,
+  so Firefox closes the tooltip and hides pending or result labels.
+  `ui/button` styles `data-disabled`, so both disabled modes look the same.
+- Build a form field from `ui/field`. Give `FieldError` the id
+  `<control id>-error` and `FieldDescription` the id `<control id>-help`. The
+  control sets `aria-invalid` and `aria-describedby`.
+- For a link that looks like a button, put `buttonVariants()` on the router
+  `Link`. A form page has one `Button variant="primary"` for its main save
+  action.
+
 ## Foundations
 
 Tokens live in the `@theme` block of `src/tailwind.css`. Keep every color in a
@@ -16,9 +84,9 @@ token so each theme can redefine it.
   paint from the saved choice or the system color scheme. `ThemeSwitcher` saves
   the choice for this browser. Use the `light:` variant only for one-off values
   that no token covers, such as provider brand colors.
-- **Charts.** Use `var(--color-*)` for series colors in SVG attributes, not hex
-  values, so they follow the theme.
-
+- **Charts.** Use `var(--color-*)` for series colors, not hex values, so they
+  follow the theme. Name series colors in the `ChartContainer` config and fill
+  each series with `var(--color-<key>)`.
 - **Surfaces.** Use the surface ladder, darkest to lightest: `bg`,
   `bg-elevated` (drawers), `surface-panel` (sidebar, cards, bubbles),
   `surface-raised` (buttons, tooltips), `control`, `surface-hover`,
@@ -51,82 +119,53 @@ token so each theme can redefine it.
   use `rounded-lg`. The composer, menus, and transcript object cards use
   `rounded-xl`. Avatars and count badges use `rounded-full`.
 
-## Shared class helpers
-
-`src/client/styles.ts` holds the few class strings that many components share.
+Shared class strings live in `src/client/styles.ts`.
 
-- `cn` joins class names.
-- `dashboardContainerClass` sets the page width.
-- `dashboardInlineLinkClass` styles a neutral underlined link inside prose.
-- `dashboardInteractiveTextClass` styles muted text that brightens on hover.
-- `dashboardComposerSurfaceClass` styles the composer surface.
+## App components
 
-## Components
-
-### Primitives
-
-- **Actions.** `Button` (`default`, `primary`, `danger`, and `size="icon"`) and
-  `ButtonLink`. Form pages use `Button tone="primary"` for their one main save
-  action. Use `ToggleButton` variants (`pill`, `segment`, `text`) for pressed
-  states, not one-off styles.
-- **Forms.** `Field` (`default`, `compact`), `TextInput`, `TextArea`, `Select`,
-  and `SearchInput`. Use `TextInput size="comfortable"` for larger mobile
-  controls. Use `TextArea prose` for instructions, not code. `Field error`
-  renders an error at `<htmlFor>-error`. The owning control must set
-  `aria-invalid` and `aria-describedby`. `Select` owns the native control and its
-  inset arrow. Use its `filter` and `sort` variants for compact controls.
 - **Status.** Use `StatusDot` for dense table or list markers. Use `StatusChip`
-  when the label must stay visible. `StatusChip` is a small dot and
-  sentence-case text, with no border or fill. It is not a control.
+  when the label must stay visible. `StatusChip` is not a control.
 - **Messages.** Use `Notice` for compact transient messages and `FormNotice`
   for wrapping form recovery text.
-- **Overlays.** `Sheet` is a local adaptation of shadcn/ui's Base UI Sheet.
-  It uses Base UI Drawer for focus, dismissal, and native swipe support. The
-  app's shared scroll lock keeps it in sync with the mobile conversation shell.
-  `SheetContent` owns side placement, backdrop fade, and slide transitions.
-  `Drawer` adds a visible header and close control. `BottomSheet` adds a swipe
-  handle and keeps content scrolling separate from gestures. Both skip motion
-  when reduced motion is set. Docked conversation details use a non-modal aside
-  so the chat stays usable. The copied component's license is in `Sheet.LICENSE`.
-  `Tooltip` and `IconButtonTooltip` own hover text.
-- **Identity.** `ActorAvatar`, `ParticipantAvatarStack`, and `ObjectIcon`.
-  `ObjectIcon` owns native Ticket, Code change, Automation, Deployment, and
-  Item icons. It uses the shared type and status mapping and the original
-  Octicons paths. Do not replace it with a provider logo or a status-only icon.
-- **Loading.** Use `Skeleton` for placeholder leaves and `PageContentSkeleton`
+- **Disclosure.** Use `ui/collapsible` for one show-or-hide section. Put a
+  `ChevronRight` with `dashboardDisclosureChevronClass` in a `group` trigger.
+  Set `hiddenUntilFound` on the content when browser find must reach closed
+  text. Closed content then keeps its box, so put margins and padding on a
+  child. Use `ui/accordion` for a set of sections with headings.
+- **Details.** `DetailsPanel` docks an aside at 1280px and above, and uses a
+  `BottomSheet` below that width. It owns Escape and the scroll frame for
+  docked panels.
+- **Identity.** `ObjectIcon` owns the native Ticket, Code change, Automation,
+  Deployment, and Item icons. Do not replace it with a provider logo or a
+  status-only icon.
+- **Loading.** Use `ui/skeleton` for placeholder leaves and `PageContentSkeleton`
   variants for page bodies. Use `PageRouteLoading` when a page keeps its real
   header above a body skeleton. Use a feature-owned loading component for
   distinct geometry, such as conversations.
 
-### Navigation
+## Navigation
 
 The dashboard has three navigation levels. Each has its own look, so the
 levels stay distinct.
 
 - **App navigation** in `layout/DashboardHeader` uses pills.
 - **Page links** use `SegmentedNav`, through `layout/SecondaryNavigation`. They
-  are underline tabs that sit on the header border. With `fill`, links share
-  the row width while their labels fit. Rows that do not fit scroll sideways.
-- **Panel switches** use `SegmentedTabs`, which draws a pill track. Pass the
-  selected value, items, change handler, and panel content. It owns tab and
-  panel labels and keyboard focus. Pass `scroll` to keep the tabs fixed while
-  the panel content scrolls. That mode fills its frame and owns the content
-  padding, so its scrollbar stays at the frame edge. `BottomSheet` content owns
-  its own padding.
+  are underline tabs that sit on the header border.
+- **Panel switches** use `ui/tabs`. Give `TabsList` an `aria-label`. Set
+  `activateOnFocus` so arrow keys select the tab.
 
-Keep collection filters in `FilterTabList`.
+Keep collection filters in `FilterTabList`. It uses `TabsList variant="line"`
+and adds the count badges.
 
-### Patterns
+## Patterns
 
 - **Layout.** `layout/` holds the shell chrome, page headers, cards, and
   section titles. `DashboardChrome` owns the sticky header block and its one
   bottom border.
-- **Directory tables and metrics.** `directory/` and `metrics/`.
-- **Charts.** Activity time-series charts own bucket labels in
-  `charts/ActivityChart` (`formatActivityDate` for axes,
-  `ActivityChartTooltip` and `formatActivityTooltipDate` for hover labels). New
-  day or hour charts compose those helpers. They do not format UTC bucket keys
-  inline.
+- **Charts.** Put `role="img"` and the chart `aria-label` on the Recharts
+  chart, so the tooltip live region stays outside the image. Day and hour
+  charts compose the `charts/ActivityChart` axis, average line, and tooltip
+  helpers. They do not format UTC bucket keys inline.
 - **Conversation mobile geometry** is a hard ownership edge:
   - `layout/VisualViewportShell` owns the fixed shell, visualViewport CSS
     variables, and body lock.
@@ -138,16 +177,14 @@ Keep collection filters in `FilterTabList`.
   dock, and must not use `ComposerDock`. Do not add viewport height, offset, or
   bottom safe-area math in page modules.
 
-### Features
-
 Feature surfaces stay under `conversations/` or `pages/` until two real callers
-share them. Transcript layout stays in `conversations/`. See
-[Transcript components](../conversations/README.md) for ownership.
+share them. See [Transcript components](../conversations/README.md) for
+transcript ownership.
 
 ## Rules
 
 - Prefer a named component on the second real use.
 - Keep Tailwind classes on the owning component.
-- Add gallery fixtures under `/dev/<section>` for new or changed shared
-  components. Keep the `/dev` index as the catalog only.
+- Check new or changed shared components on a real page with mock data and in
+  the dashboard E2E screenshots.
 - One-off page glue may stay inline when extraction only adds indirection.