元件檢查器產生器
技能為任何指定的 React/Next.js 元件,建構並生成獨立的開發檢查路徑和即時狀態偵錯工具。將狀態分為「可編輯」、「屬性」和「計算」類別,包含簡單易懂的測試驗證固定裝置和即時固定裝置載入器,嵌入固定的「上次更新時間」時間戳記方塊,並使用 tree-shaken 動態匯入強制排除零套件大小的正式版。
登入即可使用這項技能
登入 Google 開發人員個人檔案,即可查看及複製「Build It!」系列中使用的完整技能。
須具備開發人員設定檔
您不符合建立開發人員設定檔的資格。請通知 Workspace 管理員啟用這項功能。
建立開發人員設定檔
免費建立 Google 開發人員個人檔案,即可解鎖所有 Build It! 技能、規則、提示詞和構件。
加入 Builder Central 即可解鎖
一鍵領取免費的 Builder 會員徽章,即可解鎖所有 Build It! 技能、規則、提示和構件。
如何在 Google Antigravity 安裝及使用
將這項技能新增至 Google Antigravity 工作區,AI 程式設計代理就能視需要,為任何 React/Next.js 元件建構獨立的開發專用元件檢查工具路徑:
- 在專案工作區中建立
.agents/skills/component-inspector-generator/資料夾 (或依序前往 Google Antigravity 的「Customizations」>「Skills」,新增工作區技能)。 - 將下列完整 Markdown 定義儲存為該資料夾中的
SKILL.md。 - 只要想隔離元件,就可以叫用這項技能,例如:「使用 component-inspector-generator 技能,為 DailyWorkoutProposalCard 建立開發檢查器。」
- 搭配使用元件檢查器更新工具和以工作階段為範圍的檢查器編輯模式規則,即可在元件變更時自動同步檢查器。
元件檢查器生成器技能定義
將這段完整的技能定義複製到工作區,並命名為 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>
);
}
```