AgentSkillsCN

perkcord-ui-visuals

Perkcord UI 可视化信心闭环（Playwright + Storybook）

SKILL.md
--- frontmatter
name: perkcord-ui-visuals
description: Perkcord UI visual confidence loop (Playwright + Storybook)

Perkcord UI Visuals Skill

Purpose: make UI changes safely with a deterministic visual verification loop.

When To Use

  • •You changed anything user-facing in apps/web (copy, layout, component styling, subscribe/admin flows).
  • •You updated branding/theming, tier rendering, checkout UI, or admin dashboards.

Guardrails

  • •Treat visual snapshots as a contract: update them only when the change is intentional.
  • •Prefer stable test data (seeded) and stable page states (wait for navigation/data before screenshot).
  • •If a snapshot changes unexpectedly, investigate before updating.

Commands

Core web checks:

bash
npm --prefix apps/web run lint
npm --prefix apps/web run typecheck
npm --prefix apps/web run test

Playwright visuals:

bash
PLAYWRIGHT_TEST_PORT=3002 npm --prefix apps/web run test:e2e:visual

If snapshots must be updated intentionally:

bash
PLAYWRIGHT_TEST_PORT=3002 npm --prefix apps/web run test:e2e:visual:update

Storybook snapshots:

bash
npm --prefix apps/web run test:storybook

If Storybook snapshots must be updated intentionally:

bash
npm --prefix apps/web run test:storybook:update

Snapshot Locations

  • •Playwright: apps/web/e2e/*.spec.ts-snapshots/
  • •Storybook: apps/web/storybook-snapshots/

Troubleshooting Notes

  • •If Playwright hangs or ports are busy, check 3210/3211 (Convex) and 3001/3002 (Next).
  • •If admin pages show Unauthorized. or API key not configured., check PERKCORD_REST_API_KEY in both Vercel and Convex.
  • •If Storybook output looks unstyled, confirm Tailwind is applied (PostCSS pipeline in apps/web/.storybook/main.ts).

Human Review (VLM)

When snapshots change:

  • •Review the PNG diffs with a VLM before declaring the work done.
  • •Record the intent in the PR description: what changed and why.