组件检查器生成器
技能为任何指定的 React/Next.js 组件搭建并生成隔离的开发检查路由和实时状态调试程序。将状态分为 Editable、Props 和 Computed 类别,包含带有即时固件加载器的简明英语测试验证固件,嵌入固定的“上次更新时间”时间戳条状标签,并使用摇树优化动态导入强制执行零软件包大小生产排除。
登录即可使用此技能
使用您的 Google 开发者资料登录,即可查看和复制“Build It!”系列中使用的完整技能。
必须提供开发者资料
您不符合创建开发者资料的条件。请通知您的 Workspace 管理员启用此功能。
创建开发者资料
创建免费的 Google 开发者资料,解锁所有 Build It! 技能、规则、提示和工件。
加入 Builder Central 即可解锁
一键领取免费的 Builder 会员徽章,解锁所有 Build It! 技能、规则、提示和工件。
如何在 Google Antigravity 中安装和使用
将此技能添加到您的 Google Antigravity 工作区,以便 AI 编码智能体可以根据需要为任何 React/Next.js 组件搭建一个隔离的、仅限开发使用的组件检查器路由:
Component Inspector Generator 技能定义
将此完整的 skill 定义作为 SKILL.md 复制到您的工作区中。
SKILL.md (.agents/skills/component-inspector-generator/SKILL.md)
---
name: component-inspector-generator
description: >-
Scaffolds and generates an isolated development inspection route and live state debugger
for any specified React/Next.js component. Divides state into Editable, Props, and Computed
categories, includes plain-English test verification fixtures with instant fixture loaders,
embeds a fixed 'Last Updated' timestamp chip, and enforces zero-bundle-size production
exclusion using tree-shaken dynamic imports.
---
# Component Inspector Generator Skill
Use this skill whenever you need to create a dedicated, isolated development inspection route and live state workbench for a component in this application (similar to `/dev/current-set-card`).
---
## 1. Core Principles & Architecture
Every component inspector created with this skill MUST satisfy four core architectural rules:
1. **Standalone Canvas**: The component is rendered on its own without global navigation bars, headers, or distracting app shells. It lives inside a mobile-constrained preview viewport (~400px width).
2. **Three-Tier State Division**:
- **Editable State (Interactive)**: State that changes during active user operation (e.g. input fields, checkboxes, toggles). Can be changed both directly inside the component and via the inspector controls (two-way sync).
- **State from Props (Configurable)**: Static/parent configuration passed into the component (e.g. titles, counts, entity arrays). The inspector provides interactive controls and collection modifiers (add/delete items) to test different configurations.
- **Computed State (Read-Only / Derived)**: Values derived reactively using `useMemo` from Editable and Prop state (e.g. volumes, percentages, 1RM estimates, status badges). Marked with lock icons and cannot be directly mutated.
3. **Plain-English Test Fixtures**:
- Every relevant test case from the test suites or specifications is represented as a test card with clear, plain-English user descriptions (no code jargon or raw test IDs in the description).
- Each test card displays a live active status indicator (`● ACTIVE PASSING` vs `IDLE`).
- Each test card has an interactive `[Load Test Fixture]` button that instantly updates the inspector's state to recreate that test scenario in the live canvas.
4. **Zero Production Bundle Footprint (Tree-Shaking)**:
- The heavy inspector component lives in `src/dev/inspectors/[ComponentName]Inspector.tsx` outside the Next.js routing tree.
- The App Router page in `src/app/dev/[component-slug]/page.tsx` is a lightweight tree-shaken stub that conditionally dynamic-imports the inspector only when `process.env.NODE_ENV === 'development'`, and calls `notFound()` in production.
- The bundler completely removes the inspector code, mock fixtures, and test data from production builds (`npm run build`).
5. **Fixed Generation Timestamp Chip**:
- Because inspector pages do not rely on runtime introspection, they reflect a manual snapshot at a fixed point in time.
- A constant `const GENERATED_AT = 'YYYY-MM-DD HH:MM [TIMEZONE]';` must be defined at the top of the inspector file and rendered in the header as a `data-testid="last-updated-chip"` badge.
6. **Expandable Hierarchy Navigator Drawer**:
- Every inspector renders `<InspectorNavigationDrawer activeSlug="[component-slug]" />` on the left of its header.
- Provides an expandable slide-out drawer organized by the application's component hierarchy for instant navigation between created inspectors.
- **Only Created Components**: The drawer and registry ONLY display components that actually have an active inspector created. Never pre-populate speculative uncreated components or placeholders.
- **Scaffold Shared Dev Files if Missing**: If `src/dev/registry.ts` or `src/dev/components/InspectorNavigationDrawer.tsx` do not already exist, create them first.
- Any new component scaffolded with this skill must be registered in `src/dev/registry.ts`.
7. **No Automatic Page-Level Scrolling**:
- The inspector page and preview components must NEVER trigger automatic window- or page-level scrolling (e.g. via `element.scrollIntoView()` or viewport jumping) when settings change, presets are loaded, or test fixtures are activated.
- Any internal list auto-scrolling (e.g. chat feeds, exercise logs) must be strictly confined to that element's own container using `containerRef.current.scrollTop = containerRef.current.scrollHeight`. The outer browser viewport must remain stationary so the user's focus on the controls is never disrupted.
8. **Inspector Directory Home (`/dev`) & Floating Dev Trigger**:
- A central directory route at `/dev` (`src/app/dev/page.tsx` and `src/dev/inspectors/DevInspectorHome.tsx`) provides an expanded dashboard of all created components organized by hierarchy, with search, domain filtering, and launch links.
- A floating pill button (`src/dev/components/DevModeFloatingTrigger.tsx`) is mounted in `src/app/layout.tsx` strictly in development (`process.env.NODE_ENV === 'development'`) to allow jumping into the inspector directory from normal application views.
- If missing, both the home route and floating button must be created on-demand during component generation, with zero production bundle impact.
> **Skill Maintenance Policy**: Updates to this skill must reflect generic architectural standards that apply to all component inspectors across the app. Do not update this skill for one-off requests for individual components (e.g. adding a specific preset or scenario to a single component).
---
## 2. Step-by-Step Generation Workflow
When requested to create an inspection page for a target component:
### Step 1: Analyze the Component
1. Read the target component file (e.g., `src/components/[category]/[ComponentName].tsx`).
2. Catalog all props accepted by `interface [ComponentName]Props`.
3. Categorize all state variables into:
- **Editable State**: User inputs and mutable interactions (e.g. weights, reps, form fields, toggle flags).
- **Props State**: External configuration (e.g. title, step count, target values, history lists).
- **Computed State**: Derived metrics and calculations (e.g. volume, progress percentage, completion status).
4. Identify all test cases from existing test suites (e.g. in `scripts/` or `docs/architecture/client_architecture_spec.md`) relevant to this component.
### Step 2: Create the Heavy Inspector Component
Path: `src/dev/inspectors/[ComponentName]Inspector.tsx`
Use the standard layout template below. Ensure it includes:
- Top sticky header with `<InspectorNavigationDrawer activeSlug="[component-slug]" />`, `DEV INSPECTOR` tag, `<code><[ComponentName] /></code>`, the `Last Updated` chip, and quick scenario presets (e.g. *Standard*, *Completed*, *Fresh*).
- 2-Column main grid:
- Left column (`lg:col-span-5`): Standalone Component Canvas wrapped in mobile width container (`max-w-md`), plus a guidance tip box.
- Right column (`lg:col-span-7`): 3-Category State Inspector Dashboard:
- **1. Editable State** (inputs, `+`/`-` steppers, status toggle button)
- **2. State from Props** (text/numeric inputs, plus collection managers with `[Add Item]` and `[Delete]` buttons)
- **3. Computed State** (grid of read-only derived value cards with lock badges)
- Full-width bottom row (`lg:col-span-12`): Plain-English Component Test & Verification Suite with `[Load Test Fixture]` buttons.
### Step 3: Register in Component Hierarchy & Ensure Shared Dev Infrastructure
Files:
- `src/dev/registry.ts`
- `src/dev/components/InspectorNavigationDrawer.tsx`
- `src/dev/inspectors/DevInspectorHome.tsx` & `src/app/dev/page.tsx`
- `src/dev/components/DevModeFloatingTrigger.tsx` & `src/app/layout.tsx`
1. **If `src/dev/registry.ts` does not exist**: Create it with the base TypeScript interfaces (`InspectorComponentItem`, `InspectorCategory`) and export `INSPECTOR_HIERARCHY: InspectorCategory[] = []`.
2. **If `src/dev/components/InspectorNavigationDrawer.tsx` does not exist**: Create it so that `<InspectorNavigationDrawer />` is available to import in every inspector header.
3. **If `src/dev/inspectors/DevInspectorHome.tsx` or `src/app/dev/page.tsx` does not exist**: Create the central directory home route listing created components from `INSPECTOR_HIERARCHY`.
4. **If `src/dev/components/DevModeFloatingTrigger.tsx` or its integration in `src/app/layout.tsx` does not exist**: Create the trigger button and dynamically import it into `RootLayout` guarded by `process.env.NODE_ENV === 'development'`.
5. **Register the target component**: Add an entry for this newly created component under its domain category in `INSPECTOR_HIERARCHY` (create the category entry if it doesn't already exist):
```ts
{
id: '[component-slug]',
name: '[ComponentName]',
slug: '[component-slug]',
type: 'component', // or 'view'
routePath: '/dev/[component-slug]',
description: 'Plain-English summary of what this component renders and does',
}
```
> **CRITICAL**: Only include components that have actually been created. Never include uncreated, planned, or placeholder components in the registry.
### Step 4: Create the Route Stub
Path: `src/app/dev/[component-slug]/page.tsx`
(Optionally create alias re-export at `src/app/inspect/[component-slug]/page.tsx`):
```tsx
import { notFound } from 'next/navigation';
import dynamic from 'next/dynamic';
const [ComponentName]Inspector =
process.env.NODE_ENV === 'development'
? dynamic(() => import('@/dev/inspectors/[ComponentName]Inspector'), {
loading: () => (
<div className="min-h-screen bg-[#0a0b0e] flex items-center justify-center text-gray-400">
Loading Dev Inspector...
</div>
),
})
: null;
export default function [ComponentName]DevPage() {
if (process.env.NODE_ENV !== 'development' || ![ComponentName]Inspector) {
notFound();
}
return <[ComponentName]Inspector />;
}
```
### Step 5: Verification
1. Run `npx tsc --noEmit` to verify TypeScript types compile with 0 errors.
2. **Dev Server Safe Build Verification**:
- For routine iterations, rely on `npx tsc --noEmit`.
- Never run raw `npm run build` while a local `next dev` server is active, because `next build` overwrites `.next/` with production bundles and wipes out active development chunks (causing `MODULE_NOT_FOUND` / 500 errors on the user's dev server).
- If full production tree-shaking verification is needed, run in an isolated directory:
```bash
NEXT_DIST_DIR=.next-build npx next build && rm -rf .next-build
```
---
## 3. Template Reference for `[ComponentName]Inspector.tsx`
```tsx
'use client';
import React, { useState, useMemo } from 'react';
import Link from 'next/link';
import {
Lock,
Edit3,
Sliders,
Plus,
Trash2,
CheckCircle2,
Dumbbell,
Info,
Clock,
} from 'lucide-react';
import { [ComponentName] } from '@/components/.../[ComponentName]';
import { InspectorNavigationDrawer } from '@/dev/components/InspectorNavigationDrawer';
// Fixed generation timestamp for manual static tracking
const GENERATED_AT = 'YYYY-MM-DD HH:MM EDT';
export default function [ComponentName]Inspector() {
// 1. PROPS STATE
const [propA, setPropA] = useState<string>('Sample Value');
// ... other props
// 2. EDITABLE STATE
const [editableVal, setEditableVal] = useState<number>(100);
const [isCompleted, setIsCompleted] = useState<boolean>(false);
// 3. COMPUTED STATE (Derived & Read-Only)
const computedState = useMemo(() => {
return {
// calculations
};
}, [editableVal, isCompleted, propA]);
return (
<div className="min-h-screen bg-[#0a0b0e] text-gray-100 flex flex-col">
{/* Sticky Header */}
<header className="border-b border-[#262930] bg-[#111317] px-6 py-3.5 sticky top-0 z-40">
<div className="max-w-7xl mx-auto flex flex-wrap items-center justify-between gap-3">
<div className="flex items-center gap-3">
<InspectorNavigationDrawer activeSlug="[component-slug]" />
<span className="px-2.5 py-1 rounded bg-[#a3e635]/15 border border-[#a3e635]/40 text-[#a3e635] text-xs font-mono font-bold tracking-wider uppercase">
DEV INSPECTOR
</span>
<h1 className="text-base font-bold text-white flex items-center gap-2">
<code><[ComponentName] /></code>
</h1>
<span
data-testid="last-updated-chip"
className="flex items-center gap-1.5 px-2.5 py-1 rounded-full bg-[#181a20] border border-[#262930] text-[11px] font-mono text-gray-300 shadow-sm"
title="Manual snapshot generation timestamp"
>
<Clock className="w-3.5 h-3.5 text-amber-400" />
<span className="text-gray-500 font-medium">Last Updated:</span>
<span className="font-bold text-gray-200">{GENERATED_AT}</span>
</span>
</div>
{/* Quick Presets */}
<div className="flex items-center gap-2 text-xs">
<span className="text-gray-400 font-medium">Quick Presets:</span>
{/* preset buttons */}
</div>
</div>
</header>
{/* Main Grid */}
<main className="max-w-7xl mx-auto w-full p-6 grid grid-cols-1 lg:grid-cols-12 gap-8 flex-1">
{/* Left: Component Canvas */}
<section className="lg:col-span-5 flex flex-col gap-4">
<div className="bg-[#0e0f12] p-5 rounded-2xl border border-[#262930] shadow-2xl relative flex flex-col justify-center min-h-[380px]">
<div className="max-w-md mx-auto w-full">
<[ComponentName] {...props} />
</div>
</div>
</section>
{/* Right: 3-Category State Inspector */}
<section className="lg:col-span-7 flex flex-col gap-6">
{/* Category 1: Editable State */}
{/* Category 2: Props State */}
{/* Category 3: Computed State */}
</section>
{/* Bottom: Plain-English Test Cases */}
<section className="lg:col-span-12 bg-[#121418] border border-[#262930] rounded-2xl p-6 shadow-xl flex flex-col gap-6">
{/* Grid of test fixture cards with [Load Test Fixture] buttons */}
</section>
</main>
</div>
);
}
```