Maintaining the Dev Playground

The Dev Playground (apps/client/src/dev/, accessible at /dev in development) is a living gallery of every visual component in DorkOS. It exists so that designers and developers can review components in isolation, catch regressions visually, and verify that the design system is coherent.

The playground is only useful if it stays in sync with the actual application. Stale or missing showcases erode trust and let regressions slip through. This skill exists to prevent that drift.

When This Skill Applies

Assess playground impact whenever you edit files in:

• apps/client/src/layers/widgets/**/ui/** — widget UI components
• apps/client/src/layers/features/**/ui/** — feature UI components
• apps/client/src/layers/entities/**/ui/** — entity UI components
• apps/client/src/layers/shared/ui/** — shared UI primitives
• apps/client/src/dev/** — direct playground edits

After editing a UI component, ask yourself three questions:

1. Is this component a good playground candidate? (See candidacy criteria below)
2. Is it already in the playground? Check the section registries in dev/sections/.
3. If it's already there, is the showcase still accurate? Does it reflect the current props, states, and visual appearance?

Candidacy Criteria

A component belongs in the playground if it meets any of these:

• Visual and reusable — renders UI that appears in more than one place, or could
• Has multiple meaningful states — loading, empty, error, active, disabled, etc.
• Part of the design system — buttons, inputs, cards, badges, overlays
• A composed widget or panel — TasksPanel, MessagingConnections, TunnelDialog, etc.
• Complex enough to regress — more than trivial markup; has conditional rendering, animations, or data-dependent layout

A component does NOT belong if it's:

• Pure logic (hooks, utilities, stores) with no visual output
• A one-line wrapper that adds a className
• A layout container with no meaningful visual states
• A page-level route component (the playground itself IS the page-level view)

Placement Decision

Which page?

Match to the existing page structure. The playground has 5 sidebar groups, each derived from PageConfig.group in dev/playground-config.ts — check there rather than trusting this table, which is a summary and can age:

When to create a new page

Create a new page when a feature has 5+ sections that don't fit naturally into an existing page, OR when the feature is a complex multi-component system that benefits from dedicated space (e.g., a full dialog with multiple sub-views like TunnelDialog).

Soft cap: ~20 sections per page (batch 20 audit finding 20.2, DOR-1766) — where the playground's own distribution already breaks: every page under that settles fine, and the pages that crossed 2.5-3× it (Conversation, the old combined "Subsystems", Components) are the ones a reader gets lost on. When a page's section file needs the 500-line split, split the page along the same seam. The Agent & Relay / Home, Inbox & Approvals split is the worked example: the section array had already been split into features-agent-sections.ts / features-surface-sections.ts for the file-size cap, and the page above it followed the same boundary rather than staying one list. TocSidebar's category sub-headings (§ Grouping within a page) help every oversized page regardless, but they are a mitigation, not a substitute — a page that keeps growing past the cap still wants a split.

Showing one component on two pages

A component can appear on multiple pages if it genuinely belongs in both contexts — a shared primitive on the Components page and again on the feature page that composes it.

Do it by rendering, never by registering twice. The registry forbids duplicate ids and pins id === slugify(title), so one title holds exactly one entry, on one page, at one anchor. Add a second entry and the drift test goes red. Instead:

1. Export the showcase component for that one section (split it out of its file's *Showcases wrapper if it isn't already), and render it from both pages.
2. Leave the registry entry where it is, so the existing /dev/<page>#<anchor> keeps working.
3. Compose the borrowing page's TOC from both halves in its PageConfig.sections — [...OWN_SECTIONS, ...borrowed]. That is legal because PLAYGROUND_REGISTRY is the union of the per-page arrays, not of PAGE_CONFIGS[].sections.

The accepted cost: a borrowed section still groups under its owning page in Cmd+K. Say so on the borrowing page rather than letting the next person discover it. Worked example: dev/pages/IdentityPage.tsx and IDENTITY_CROSS_LISTED in dev/playground-config.ts.

Grouping within a page

Group components that work together. The category field drives the TOC: TocSidebar renders one sub-heading per distinct category, keyed by name rather than position (batch 20 audit finding 20.3/I2, DOR-1766) — a category's entries don't need to be adjacent in the section array, since every section sharing a name lands under the same heading regardless of where else it appears. Cmd+K still groups by page only (PlaygroundSearch); category has never been a search grouping. Use the feature/subsystem name — "Relay", "Mesh", "Tasks", "Identity" — the same words a reader would look for in the TOC.

The Parity Problem

The goal: render the SAME component in both the playground and the application. Never rebuild a layout or composition in the playground — if the widget changes in the app, it should change in the playground automatically.

Current state

Most showcases render only leaf components (individual cards, empty states, buttons). Full widget panels are usually NOT showcased — only their children are — which means the composed experience (how the parts work together) is invisible in the playground for most of them. TasksPanel and relay's MessagingConnections are the worked examples (DOR-1766): each is showcased with an isolated, pre-seeded QueryClient per the data-injection pattern below. Mesh's composed panels, TopologyPanel and DiscoveryView, are not showcased yet.

The pattern to follow

When showcasing a composed widget (a dialog, panel, or multi-component feature):

1. Separate content from chrome. The dialog wrapper (e.g., TasksDialogWrapper) handles ResponsiveDialog chrome and open/close state. The content component (e.g., TasksPanel) handles the actual UI. The playground should render the content component, not the dialog wrapper.

App renders:                     Playground renders:
DialogWrapper                    PlaygroundSection
└─ ResponsiveDialog                └─ ShowcaseDemo
   └─ ContentPanel  ←──────────────── └─ ContentPanel (same component!)

2. Support data injection via props. Components that only get data from hooks (TanStack Query, Zustand) can't render with mock data in the playground. Refactor to accept data via props, with the hook as the default:

// BEFORE: tightly coupled to hooks — can't showcase with mock data
function WidgetPanel() {
  const { data } = useWidgetData();
  return <ItemList items={data} />;
}

// AFTER: accepts props OR falls back to hook
interface WidgetPanelProps {
  items?: Item[];
}

function WidgetPanel({ items: itemsProp }: WidgetPanelProps) {
  const query = useWidgetData();
  const items = itemsProp ?? query.data;
  return <ItemList items={items} />;
}

This lets the playground pass mock data while the app continues using the hook. No duplication.

2b. Or seed an isolated QueryClient, when the component is TanStack-Query-only and a props refactor isn't warranted. A component whose only obstacle is useQuery — no Zustand, no other outside state — can be shown as-is: wrap it in its own QueryClient (retry: false, staleTime: Infinity so nothing refetches against a server that isn't running) and setQueryData the exact keys it reads, then render the REAL component inside a <QueryClientProvider client={...}>. MarketplaceShowcases.tsx, SidebarShowcases.tsx and (DOR-1766) TasksShowcases.tsx/RelayShowcases.tsx/ConnectionsShowcases.tsx all use this. Export the query key alongside its hook (export const CATALOG_KEY = …) so the showcase can import it rather than re-typing the array by hand. Check every hook the component reaches for a null-vs-undefined landmine first: the playground's ambient transport resolves every unseeded call to null, and a destructured default (const { data = [] } = useX()) only fires on undefined — so a hook whose consumer does data.map(...) with no optional chaining will crash on an unseeded query. Either seed that key too, or confirm the consumer already guards with ?./??/an explicit if (!data).

3. Support controlled state for state machines. Components with internal state machines (like TunnelDialog's landing/setup/connecting/connected/error views) should accept an optional initialState or state prop so the playground can showcase each state independently:

// Playground can now render each state:
<TunnelContent initialView="connecting" />
<TunnelContent initialView="connected" mockData={connectedData} />
<TunnelContent initialView="error" mockData={errorData} />

4. Keep mock data alongside showcases. Mock data factories live in dev/mock-factories.ts and dev/mock-samples/ (split by domain — DOR-1766, finding 20.8 — and re-exported from its index.ts). When adding a new showcase that needs mock data, add the factories there rather than inline in the showcase file. This keeps mock data reusable and the showcases focused on layout.

When to refactor

If a component can't be showcased without duplicating its layout, that's a signal to refactor. Common refactors:

• Extract content from dialog/sheet wrapper — make the content renderable standalone
• Add optional prop overrides for hook data — let props take precedence over hooks
• Add initialState prop to state machines — let the playground control which view renders
• Extract sub-views into named components — makes individual states showcaseable

These refactors improve the component's testability and composability beyond just playground support. They're worth doing.

Implementation Checklist

When adding a component to the playground:

1. Add section metadata

Add entries to the appropriate section file in dev/sections/:

// dev/sections/features-agent-sections.ts
{
  id: 'tunneldialog',           // anchor ID — lowercase, no spaces
  title: 'TunnelDialog',        // display name
  page: 'features',             // which page (must match Page type)
  category: 'Tunnel',           // groups the TOC — same name anywhere in the array shares one heading
  keywords: ['tunnel', 'remote', 'ssh', 'connect', 'security'],
}

The id must be the slugified version of the title (the PlaygroundSection component auto-generates anchors from its title prop via slugify()).

2. Create the showcase file

Create dev/showcases/TunnelShowcases.tsx:

import { PlaygroundSection } from '../PlaygroundSection';
import { ShowcaseLabel } from '../ShowcaseLabel';
import { ShowcaseDemo } from '../ShowcaseDemo';
import { TunnelContent } from '@/layers/features/settings';

export function TunnelShowcases() {
  return (
    <>
      <PlaygroundSection
        title="TunnelDialog"
        description="Tunnel connection manager with multi-step state machine."
      >
        <ShowcaseLabel>Landing</ShowcaseLabel>
        <ShowcaseDemo>
          <TunnelContent initialView="landing" />
        </ShowcaseDemo>

        <ShowcaseLabel>Connected</ShowcaseLabel>
        <ShowcaseDemo>
          <TunnelContent initialView="connected" mockData={connectedMock} />
        </ShowcaseDemo>
      </PlaygroundSection>
    </>
  );
}

Guidelines:

• One showcase file per feature/subsystem, not per component
• Use ShowcaseLabel to distinguish variants within a section
• Use ShowcaseDemo (with responsive prop when layout is width-sensitive) to wrap each demo
• Import the REAL component — never recreate its markup
• Pass mock data via props, using factories from dev/mock-factories.ts

Imports: barrel when there is one, leaf when there isn't. If the slice's index.ts already exports the symbol, import it from @/layers/features/<slice> like every other consumer does — the playground is the first place a new contributor reads, so it should model the convention. When the barrel does not export it, import the leaf module directly. That is allowed here and nowhere else: showing a leaf component in isolation is this directory's whole job, and widening a feature's public API just to feed a showcase would be the worse trade. Do not add an export to a barrel only for the playground.

3. Add to the page component

Import the showcase in the relevant page file (dev/pages/FeaturesPage.tsx):

import { TunnelShowcases } from '../showcases/TunnelShowcases';

// Add inside the PlaygroundPageLayout:
<TunnelShowcases />;

4. Create a new page (if needed)

A new page is seven touch points, not six. The seventh is a test file, and missing it turns CI red rather than the browser:

1. Add the Page type union member in dev/playground-registry.ts
2. Create dev/sections/new-page-sections.ts exporting NEW_PAGE_SECTIONS
3. Export it from dev/playground-registry.ts — the named re-export and the aliased import spread into PLAYGROUND_REGISTRY
4. Add a PageConfig entry in dev/playground-config.ts (group, icon, description, path)
5. Create dev/pages/NewPage.tsx using PlaygroundPageLayout
6. Add the page component to PAGE_COMPONENTS in dev/playground-pages.ts (plus its import)
7. Add the array to dev/__tests__/playground-registry.test.ts — both its import and the hardcoded union in "PLAYGROUND_REGISTRY equals the union of all page-level arrays". That assertion lists every section array by name, so a new one that is not there fails the test even though the page works.

Then run pnpm vitest run apps/client/src/dev/__tests__/playground-registry.test.ts — green there proves union membership, unique ids, id === slugify(title), and that every rendered section is registered and every registered section is rendered.

Quality Checks

When reviewing an existing playground showcase, verify:

• Accuracy — Does the showcase still match the component's current props interface? Are there new props or states not represented?
• Completeness — Are all meaningful states shown? (default, loading, empty, error, disabled, active)
• Parity — Is the showcase rendering the actual component, or a recreation? If it's a recreation, flag it for refactoring.
• Mock data — Is mock data realistic? Would a reviewer understand what this component looks like with real data?
• Grouping — Is this showcase on the right page and in the right category? Has the component's role changed since it was added?

Files to Know