Working With Playground App

---
name: 'working-with-playground-app'
description: 'This skill provides guidance for building UI/UX prototypes in the Packmind playground app. It should be used when creating a new prototype, iterating on an existing prototype, or working with files in apps/playground/. Triggers on mentions of "playground", "prototype", or direct work within the apps/playground/ directory.'
---

# Working With the Playground App

## Overview

The playground app (`apps/playground/`) is a standalone Vite + React environment for iterating on UI/UX of Packmind features — both new and existing. Prototypes built here are meant to be easily convertible into production-ready code.

## UX Design Thinking

Before writing any code, think like a UX designer. The playground exists to explore how a feature *feels* to use — not just how it looks. Apply these principles to every prototype:

### Design All States First

Never prototype only the happy path. Before building, identify and plan for every state the user might encounter:

- **Empty state** — What does the user see before any data exists? Guide them toward the first action.
- **Loading state** — What appears while data is being fetched? Use skeletons or spinners to set expectations.
- **Populated state** — The standard view with data. Test with both minimal and full datasets.
- **Error state** — What happens when something fails? Show a clear message and a recovery path.
- **Edge cases** — What about a single item? Hundreds? An extremely long name that might overflow?

Prototype each state explicitly — use local state toggles or tabs to let reviewers switch between them.

### Use Realistic, Varied Data

Mock data should stress-test the design, not just fill space:

- Include **long names** that could wrap or overflow, **short names** that could look sparse, and **special characters**.
- Vary counts: 0 items, 1 item, a handful, and many (50+). Layouts that work for 5 items often break at 50.
- Include **missing optional fields** — not every record will be complete.
- Use **recognizable but realistic** content so reviewers can evaluate readability, not just layout.

### Design for Interaction

Prototypes should be clickable and stateful, not static mockups:

- Wire up buttons, toggles, and form inputs with local state so reviewers experience the flow.
- Simulate async operations (e.g., a brief delay before showing a success toast) to prototype timing and feedback.
- Show what happens *after* an action — does a list update? Does a confirmation appear? Does the user navigate somewhere?

### Establish Visual Hierarchy

Guide the user's eye to what matters most:

- **One primary action per view.** If everything is bold, nothing is. Use a primary button for the main action, secondary/ghost for the rest.
- **Group related information** with spacing and borders, not just proximity.
- **Size and weight signal importance.** Headings, subheadings, and body text should create a clear reading order.
- **Use whitespace deliberately** — it separates sections and reduces cognitive load.

### Make Affordance Obvious

Users should understand what they can do without instructions:

- **Clickable elements should look clickable.** Buttons look like buttons, links look like links.
- **Destructive actions should look dangerous** — use red/warning styling and require confirmation.
- **Disabled states should be visually distinct** and ideally explain *why* they're disabled (tooltip or helper text).
- **Feedback should be immediate** — hover states, active states, and loading indicators tell the user the system responded.

### Manage Information Density

Show enough to be useful, hide enough to avoid overwhelm:

- **Lead with a summary, offer detail on demand.** Use accordions, expandable rows, or drill-down views for secondary information.
- **Don't front-load every field.** Tables and lists should show the most important 3–5 columns; offer a detail view for the rest.
- **Use progressive disclosure** — reveal complexity as the user engages deeper (overview → detail → advanced settings).

### Stay Consistent With the Product

Before designing something new, check how the existing product handles similar patterns:

- **Browse `apps/frontend/src/domain/`** for existing feature implementations. If a similar interaction exists, match its layout and behavior before inventing alternatives.
- **Reuse established patterns** — if the product uses a sidebar + main content layout for listings, don't prototype a card grid for the same type of data without good reason.
- **Follow the same information architecture** — similar actions in the same position, similar data in the same format.
- When diverging from existing patterns, call it out explicitly so reviewers can evaluate the change intentionally.

## Running the Playground

To start the playground dev server:

```bash
nx dev playground
```

The app runs on **localhost:4300**. It is not part of the Docker Compose setup — it runs in isolation via Vite's dev server.

## Creating a New Prototype

### 1. Create the Prototype Directory

Each prototype lives under `apps/playground/src/prototypes/`. For non-trivial prototypes, create a dedicated folder organized by domain — mirroring the frontend app structure. Consult `references/frontend-domain-structure.md` for the domain folder list.

```
apps/playground/src/prototypes/
├── index.ts                          # Prototype registry
├── ButtonsPrototype.tsx              # Simple single-file prototype
└── my-feature/                       # Multi-component prototype
    ├── MyFeaturePrototype.tsx        # Root component (entry point)
    ├── components/
    │   ├── domain-a/
    │   │   ├── SomeComponent.tsx
    │   │   └── AnotherComponent.tsx
    │   └── domain-b/
    │       └── SomethingElse.tsx
    └── types.ts                      # Shared types for this prototype
```

For simple prototypes (e.g., showcasing a single component), a single file is acceptable.

### 2. Build the Prototype Component

Create a default-exported React component:

```tsx
import { PMBox, PMHeading } from '@packmind/ui';

export default function MyFeaturePrototype() {
  return (
    <PMBox padding="6">
      <PMHeading size="lg">My Feature</PMHeading>
      {/* Prototype content */}
    </PMBox>
  );
}
```

### 3. Register the Prototype

Add the prototype to `apps/playground/src/prototypes/index.ts`:

```tsx
import MyFeaturePrototype from './my-feature/MyFeaturePrototype';

export const prototypes: Prototype[] = [
  // ... existing prototypes
  {
    name: 'My Feature',
    description: 'Optional description',
    component: MyFeaturePrototype,
  },
];
```

The prototype will appear in the dropdown selector in the playground nav bar.

## Mandatory Rules

### Data

- **Always use stub/mock data.** Never make actual calls to the backend. Define realistic mock data inline or in a dedicated `data.ts` file within the prototype folder.

### Dependencies

- **Never install new dependencies** without explicit user approval.
- **Never modify files outside `apps/playground/`.** No changes to other apps or packages.

### Reusing Existing Code

- Prototypes **can** import presentational components and types from the frontend app (`apps/frontend/src/`) and shared type packages (`packages/`).
- Prototypes **must not** import services, gateways, hooks with side effects, or anything that calls the backend.

### UI Components

- Use `PM*` components from `@packmind/ui` (e.g., `PMBox`, `PMButton`, `PMHeading`, `PMVStack`, `PMHStack`, `PMText`).
- When a needed component is not available in the Packmind UI kit, browse [Chakra UI v3 components](https://www.chakra-ui.com/docs/components) for reference, then map to the corresponding `PM*` wrapper before using. If no wrapper exists, ask the user before using the raw Chakra component.
- Icons come from `react-icons/lu` (Lucide icons, prefixed with `Lu`).

### Code Quality

- Prototypes **must** be production-ready in structure. Follow React best practices: split responsibility, create as many components as needed, organize by domain.
- Use `useState`, `useCallback`, `useMemo` for local state and performance.
- Define TypeScript types for all data structures.
- Keep components focused — each component should have a single responsibility.

## Resources

### references/

- `frontend-domain-structure.md` — Domain folder structure from the frontend app, to guide component organization in prototypes.