Skip to main content

When to Use This Skill

✅ Use when:

  • Developing React components in isolation with live preview
  • Testing frontend components with Playwright automation
  • Performing visual regression testing on UI components
  • Running accessibility audits with axe-core integration
  • Setting up hot-reload development environment for React
  • Creating component showcases or style guides

❌ Don't use when:

  • Working with non-React frameworks (Vue, Svelte, Angular)
  • Building full applications (not isolated components)
  • Testing backend APIs or server logic
  • Only need static HTML/CSS previews
  • Component testing is already covered by existing tools (Storybook, etc.)

Core Capabilities​

  • Live Preview: Vite-powered development server with hot module replacement (HMR)
  • Component Management: Register, unregister, and switch between multiple components
  • Browser Automation: Playwright integration for automated testing and screenshots
  • Accessibility Testing: Built-in axe-core integration for WCAG compliance
  • Visual Regression: Screenshot capture and comparison for UI consistency
  • Multi-Framework: React 18 with potential for Vue/Svelte extensions

Description​

Universal React component viewer and testing environment for CODITECT frontend development. Provides live preview, hot reload, Playwright integration, and automated testing capabilities.

Capabilities​

Component Management​

  • Register/unregister components
  • Live preview with hot module replacement
  • Multi-component view switching
  • Component metadata tracking

Development Server​

  • Vite-powered dev server (port 5173 default)
  • React 18 with StrictMode
  • Tailwind CSS 3 integration
  • Lucide React icons
  • Auto-open browser

Testing Integration​

  • Playwright browser automation
  • Screenshot capture
  • Accessibility testing (axe-core)
  • Visual regression testing
  • Performance profiling

CLI Interface​

  • coditect-view dev - Start development server
  • coditect-view add <path> - Add component to registry
  • coditect-view remove <name> - Remove component
  • coditect-view list - List registered components

Usage​

Via Agent​

# Start component viewer

## How to Use This Skill

1. Review the patterns and examples below
2. Apply the relevant patterns to your implementation
3. Follow the best practices outlined in this skill

Task(
    subagent_type="frontend-development-agent",
    prompt="Start component viewer for MyComponent.jsx"
)

# Add component to viewer
Task(
    subagent_type="frontend-development-agent",
    prompt="Add component at path/to/MyComponent.jsx to viewer with name 'My Component'"
)

Via Slash Command​

# Start viewer
/view

# View specific component
/view MyComponent

# With custom port
/view MyComponent --port 3000

Via CLI​

# Navigate to viewer directory
cd tools/component-viewer

# Install dependencies (first time only)
npm install

# Add a component
node cli.js add ../../path/to/Component.jsx --name "My Component"

# List registered components
node cli.js list

# Start dev server
node cli.js dev

# Or use npm scripts
npm run dev

Direct Script Access​

# From coditect-core root
./scripts/frontend/start-viewer.sh

# With component path
./scripts/frontend/start-viewer.sh path/to/Component.jsx

# With options
./scripts/frontend/start-viewer.sh --port 3000 --no-open

Configuration​

Component Registry​

Location: tools/component-viewer/components/registry.json

{
  "components": [
    {
      "id": "my-component",
      "name": "My Component",
      "path": "/absolute/path/to/MyComponent.jsx",
      "addedAt": "2025-12-02T12:00:00Z"
    }
  ]
}

Viewer Config​

Location: tools/component-viewer/.env (optional)

VIEWER_PORT=5173
VIEWER_OPEN=true
VIEWER_HOST=localhost

Playwright Config​

Location: tools/component-viewer/playwright.config.js

export default {
  testDir: './tests',
  use: {
    baseURL: 'http://localhost:5173',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
}

File Structure​

tools/component-viewer/
├── package.json              # Dependencies and scripts
├── cli.js                    # CLI interface
├── vite.config.js            # Vite configuration
├── tailwind.config.js        # Tailwind CSS config
├── postcss.config.js         # PostCSS config
├── playwright.config.js      # Playwright config
├── index.html                # HTML template
├── src/
│   ├── main.jsx              # React entry point
│   ├── App.jsx               # Main app component
│   ├── ComponentRegistry.jsx # Component loader
│   └── index.css             # Global styles
├── components/
│   ├── registry.json         # Component registry
│   └── [copied-components]   # User components
├── tests/
│   ├── component.spec.js     # Playwright tests
│   └── accessibility.spec.js # A11y tests
└── screenshots/              # Test screenshots

Dependencies​

Production​

  • react: ^18.3.1
  • react-dom: ^18.3.1
  • lucide-react: ^0.263.1
  • @radix-ui/react-tabs: ^1.0.4
  • @radix-ui/react-dialog: ^1.0.5

Development​

  • vite: ^6.0.3
  • @vitejs/plugin-react: ^4.3.4
  • tailwindcss: ^3.4.17
  • autoprefixer: ^10.4.20
  • postcss: ^8.4.49

Testing​

  • @playwright/test: ^1.40.0
  • axe-core: ^4.8.0
  • @axe-core/playwright: ^4.8.0

Integration with CODITECT​

With Other Skills​

# Use with git-workflow
Task(prompt="Start viewer, then commit changes")

# Use with documentation-librarian
Task(prompt="Generate component docs and add to viewer")

# Use with testing-specialist
Task(prompt="Run full test suite on viewer components")

With Hooks​

# Pre-commit hook validates components
.coditect/hooks/pre-commit-frontend-test.sh

# Post-merge updates component registry
.coditect/hooks/post-merge-update-viewer.sh

Examples​

Example 1: Add and View Component​

# Terminal 1: Add component
cd tools/component-viewer
node cli.js add ../../../path/to/UserCard.jsx --name "User Card"

# Terminal 2: Start viewer
npm run dev

# Browser opens at http://localhost:5173
# Component visible in viewer with hot reload

Example 2: Playwright Testing​

# Create test file
cat > tests/user-card.spec.js << 'EOF'
import { test, expect } from '@playwright/test';

test('UserCard renders correctly', async ({ page }) => {
  await page.goto('/');

  // Check component loads
  const card = page.locator('.user-card');
  await expect(card).toBeVisible();

  // Take screenshot
  await page.screenshot({ path: 'screenshots/user-card.png' });

  // Check accessibility
  const accessibilityScanResults = await new AxeBuilder({ page }).analyze();
  expect(accessibilityScanResults.violations).toEqual([]);
});
EOF

# Run tests
npx playwright test

# View report
npx playwright show-report

Example 3: Visual Regression​

# Take baseline
npx playwright test --update-snapshots

# Run tests (will compare to baseline)
npx playwright test

# View diff images
open test-results/[test-name]/[browser]-actual.png
open test-results/[test-name]/[browser]-diff.png

Troubleshooting​

Port Already in Use​

# Change port
VIEWER_PORT=3001 npm run dev

# Or kill existing process
lsof -ti:5173 | xargs kill -9

Component Not Found​

# Check registry
node cli.js list

# Re-add component
node cli.js add path/to/Component.jsx

# Verify path is absolute
node cli.js add $(pwd)/path/to/Component.jsx

Playwright Browser Not Installed​

# Install browsers
npx playwright install

# Install system dependencies
npx playwright install-deps

Hot Reload Not Working​

# Clear Vite cache
rm -rf node_modules/.vite

# Restart dev server
npm run dev

Performance​

  • Startup Time: <2 seconds (cold start), <500ms (warm)
  • Hot Reload: <100ms
  • Build Time: <5 seconds for production build
  • Test Execution: ~2-5 seconds per test (headless)
  • Screenshot Capture: ~500ms per screenshot

Security​

  • No external API calls
  • Local dev server only
  • CORS enabled for localhost
  • No sensitive data in component registry
  • Git-ignored node_modules and test artifacts

Future Enhancements​

  • Storybook integration
  • Component prop controls
  • Mobile device emulation
  • Network throttling
  • Performance budgets
  • Chromatic visual testing
  • Component templates
  • Multi-framework support (Vue, Svelte)

Success Output​

When this skill completes successfully, output:

✅ SKILL COMPLETE: component-viewer

Component Viewer Ready:
- [x] Development server started on port [port]
- [x] Component registered: [component-name] ([component-path])
- [x] Browser opened at http://localhost:[port]
- [x] Hot reload active
- [x] Playwright testing environment ready

Outputs:
- Component registry: tools/component-viewer/components/registry.json
- Dev server: http://localhost:[port]
- Test results: tools/component-viewer/test-results/ (if tests run)
- Screenshots: tools/component-viewer/screenshots/ (if captured)

Performance:
- Startup time: [time]ms (target: <2s cold, <500ms warm)
- Hot reload latency: [time]ms (target: <100ms)

Completion Checklist​

Before marking this skill as complete, verify:

  • Component added to registry successfully
  • Dev server running without errors
  • Browser opens automatically at correct URL
  • Component renders correctly in viewer
  • Hot module replacement working (edit triggers reload)
  • No console errors in browser dev tools
  • Tailwind CSS styles applied correctly
  • Playwright tests passing (if applicable)

Failure Indicators​

This skill has FAILED if:

  • ❌ Port already in use and viewer cannot start
  • ❌ Component path invalid or file not found
  • ❌ Registry update fails (JSON corruption)
  • ❌ Vite server crashes on startup
  • ❌ Component fails to render (React errors)
  • ❌ Hot reload not working (requires manual refresh)
  • ❌ Playwright browser installation failed
  • ❌ Accessibility violations detected (axe-core failures)

When NOT to Use​

Do NOT use this skill when:

  • Non-React framework components (Vue, Svelte, Angular)
    • Solution: Use framework-specific preview tools
  • Full application development (not isolated components)
    • Solution: Use standard dev server (npm run dev)
  • Backend API testing
    • Solution: Use API testing tools (Postman, Insomnia)
  • Static HTML/CSS only (no React needed)
    • Solution: Use simple HTTP server (python -m http.server)
  • Component testing already covered by Storybook
    • Solution: Use existing Storybook setup
  • Production deployment previews
    • Solution: Use production build preview tools
  • Non-browser components (CLI tools, Node.js libraries)
    • Solution: Use unit tests instead of visual preview

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Adding full app to viewerIntended for isolated componentsExtract component to standalone file
Not cleaning up old componentsRegistry bloat, confusionRemove unused components from registry
Ignoring console errorsSilent failuresMonitor browser console during development
Skipping accessibility testsWCAG violationsRun axe-core tests regularly
Using hardcoded portsConflicts with other servicesUse configurable port (VIEWER_PORT env var)
No test coverageRegressions undetectedWrite Playwright tests for critical components
Leaving dev server runningResource wasteStop server when done
Not using hot reloadManual refresh overheadEnsure HMR enabled in Vite config
Adding components with external deps not installedRendering failuresEnsure all dependencies in package.json
Visual regression without baselinesNo comparison pointGenerate snapshot baselines first

Principles​

This skill embodies the following CODITECT principles:

#1 Recycle → Extend → Re-Use → Create

  • Reuses Vite dev server (industry standard)
  • Extends with component registry management
  • Creates isolated testing environment on top of React

#2 Automation with Minimal Human Intervention

  • Auto-opens browser on server start
  • Auto-reloads on file changes (HMR)
  • Auto-installs dependencies (npm install on first run)
  • Auto-generates test boilerplate

#3 Separation of Concerns

  • Component viewer separate from component implementation
  • Testing isolated from development server
  • Registry management independent of rendering

#4 Keep It Simple

  • Minimal configuration required
  • Standard React patterns (no custom abstractions)
  • CLI with simple commands (dev, add, remove, list)

#5 Eliminate Ambiguity

  • Explicit component registration (not auto-discovery)
  • Clear error messages for missing dependencies
  • Validation of component paths before adding

#6 Clear, Understandable, Explainable

  • Visual component preview (see what you're building)
  • Browser dev tools integration
  • Clear test reports with screenshots

#8 No Assumptions

  • Validates component path exists before adding
  • Checks port availability before starting server
  • Confirms Playwright installed before running tests
  • Verifies React component structure before rendering

Status: Production Ready Last Updated: 2025-12-02 Maintainer: CODITECT Core Team