/prowler-ui

name: prowler-ui
description: >
  Prowler UI-specific patterns. For generic patterns, see: typescript, react-19, nextjs-16, tailwind-4.
  Trigger: When working inside ui/ on Prowler-specific conventions (shadcn, folder placement, actions/adapters, shared types/hooks/lib).
license: Apache-2.0
metadata:
  author: prowler-cloud
  version: "1.2"
  scope: [root, ui]
  auto_invoke:
    - "Creating/modifying Prowler UI components"
    - "Reviewing Prowler UI components"
    - "Working on Prowler UI structure (actions/adapters/types/hooks)"
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task

Related Generic Skills

• `typescript` - Const types, flat interfaces
• `react-19` - No useMemo/useCallback, compiler
• `nextjs-16` - App Router, Server Actions
• `tailwind-4` - cn() utility, styling rules
• `zod-4` - Schema validation
• `zustand-5` - State management
• `ai-sdk-5` - Chat/AI features (installed: AI SDK 6, `@ai-sdk/react` 3)
• `vitest` - Unit (jsdom) and browser integration tests
• `playwright` - E2E testing (see also `prowler-test-ui`)

Tech Stack (Versions)

Source of truth is `ui/package.json` (pinned exact versions). At 5.48:

Next.js 16.4 | React 19.2 (React Compiler on) | Tailwind 4.1 | shadcn/ui + Radix
Zod 4.4 | React Hook Form 7.62 | Zustand 5.0 | NextAuth 5.0.0-beta.32 | Recharts 2.15
AI SDK 6 (`ai`) + @ai-sdk/react 3 | LangChain/LangGraph (@langchain/*) for Lighthouse
Vitest 4.1 | Playwright 1.56 | TypeScript 5.5 | pnpm 11 | Node >= 22.13

CRITICAL: Component Library Rule

• **ALWAYS**: Use `shadcn/ui` + Tailwind (`components/shadcn/`)
• **NEVER**: Add components to `components/ui/` (temporary re-export shims for the prowler-cloud overlay only)

Design System Discipline (REQUIRED)

Applies to ALL UI work. The design system is the single source of truth — reuse it exactly, extend it deliberately.

• **Reuse first, never reinvent.** Before building anything, search `components/shadcn/` and existing usages in the codebase for an equivalent. Do NOT create a custom component, modal wrapper, or primitive when one already exists.
• **Use exactly the defined variants/styles — no more, no less.** At the call site, drive appearance through the component's `variant`/`size`/`tone` props. Never add ad-hoc visual `className` (color, opacity, hover/focus/disabled, spacing-for-looks) to shared controls (`Button`, `SelectTrigger`, `SelectItem`, `Modal`, badges…), and never skip the correct semantic variant.
• **Modals**: only `@/components/shadcn/modal`. **Selects**: `components/shadcn/select`.
• **Colors**: reuse existing semantic tokens from `ui/styles/globals.css`. No raw Tailwind color utilities (e.g. `bg-blue-950/40`), no hex. If no token fits, STOP and ask the design owner — do not invent or near-duplicate tokens.
• **Need a genuinely new variant/token?** That is a design-system change: add it to the shared component API (with design sign-off), then consume it. It is never a call-site decision.

When reviewing UI PRs, flag: custom modals/primitives that duplicate shadcn, call-site visual `className` on shared controls, raw color utilities, and new variants/tokens introduced without going through the shared component API.

DECISION TREES

Component Placement

New UI primitive?   → components/shadcn/ (shadcn/ui + Tailwind)
Used by 1 domain?   → components/{domain}/
Used by 2+ domains? → components/shared/
Needs state/hooks?  → "use client"
Server component?    → No directive needed

Code Location

Server action      → actions/{feature}/{feature}.ts
Data transform     → actions/{feature}/{feature}.adapter.ts
Types (shared 2+)  → types/{domain}.ts
Types (local 1)    → {feature}/types.ts
Utils (shared 2+)  → lib/
Utils (local 1)    → {feature}/utils/
Hooks (shared 2+)  → hooks/
Hooks (local 1)    → {feature}/hooks.ts
UI primitive       → components/shadcn/
Domain component   → components/{domain}/

> **Deprecated:** `components/ui/` is a temporary re-export shim that maps > legacy import paths to `components/shadcn/` for the prowler-cloud overlay. > HeroUI is fully removed. Never add or import components here — use > `@/components/shadcn` (primitives) or `@/components/{domain}` instead. > Delete the shim once the cloud repo migrates to `@/components/shadcn`.

Styling Decision

Tailwind class exists? → className
Dynamic value?         → style prop
Conditional styles?    → cn()
Static only?           → className (no cn())
Recharts/library?      → CHART_COLORS constant + var()

Scope Rule (ABSOLUTE)

• Used 2+ places → `lib/` or `types/` or `hooks/` (components go in `components/{domain}/`)
• Used 1 place → keep local in feature directory
• **This determines ALL folder structure decisions**

Project Structure

ui/
├── app/
│   ├── (auth)/              # Auth pages (login, signup)
│   └── (prowler)/           # Main app
│       ├── compliance/
│       ├── findings/
│       ├── providers/
│       ├── scans/
│       ├── services/
│       └── integrations/
├── components/
│   ├── shadcn/              # shadcn/ui primitives (USE THIS)
│   ├── shared/             # Cross-domain composed components (2+ domains)
│   ├── ui/                  # DEPRECATED shim → re-exports shadcn (do not use)
│   ├── {domain}/            # Domain-specific (compliance, findings, providers, etc.)
│   ├── filters/             # Filter components
│   ├── graphs/              # Chart components
│   └── icons/               # Icon components
├── actions/                 # Server actions ({feature}/{feature}.ts + .adapter.ts + tests)
├── types/                   # Shared types
├── hooks/                   # Shared hooks
├── lib/                     # Utilities (cn() in lib/utils.ts)
├── store/                   # Zustand stores ({feature}/store.ts, re-exported from store/index.ts)
├── __tests__/               # Vitest shared harness (render-browser, MSW handlers)
├── tests/                   # Playwright E2E
├──