playbooks

home / skills / velcrafting / codex-skills / component-scaffold

component-scaffold skill

/skills/frontend/component-scaffold

This skill creates a new UI component aligned with repo conventions, including structure, typing, styling, and exports for seamless integration.

npx playbooks add skill velcrafting/codex-skills --skill component-scaffold

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.3 KB
---
name: component-scaffold
description: Create a new UI component consistent with repo conventions (structure, typing, styling, exports).
metadata:
  short-description: New component scaffold
  layer: frontend
  mode: write
  idempotent: false
---

# Skill: frontend/component-scaffold

## Purpose
Create a new UI component consistent with repo conventions (file layout, TypeScript usage, styling system, exports, naming).

This skill is the default entry point for adding UI surfaces.

---

## Inputs
- Component name
- Target location (route, feature folder, or component library folder)
- Brief responsibility statement (1–2 sentences)
- Props: names + types (if known)
- Any dependencies on existing components or design system
- Repo profile (preferred): `<repo>/REPO_PROFILE.json`

---

## Outputs
- New component file(s)
- Export wiring (barrel/index) if the repo uses it
- Minimal usage example only if repo conventions require it (story/demo/test)

---

## Non-goals
- Implement business/domain rules
- Change API contracts
- Large refactors unrelated to the new component

---

## Workflow
1) Read repo conventions (prefer `REPO_PROFILE.json`; otherwise infer from existing nearby components).
2) Choose correct placement (nearest existing pattern wins).
3) Create the component with minimal API surface:
   - small prop surface
   - sane defaults
   - predictable rendering
4) Wire exports the way the repo already does (or do nothing if it does not).
5) Add minimal usage/example only if required by repo conventions.
6) Run required validations (from repo profile if present).

---

## Checks
- Component compiles (typecheck passes if configured)
- Component renders without runtime errors (smoke-level)
- Export wiring is correct (import path works)
- No unrelated files modified

---

## Failure modes
- Conventions unclear → use `$ask-questions-if-underspecified` (framework, file naming, export pattern).
- Wrong placement → relocate to match nearest existing pattern.
- Missing exports → add wiring consistent with repo patterns.
- Component grows too large during creation → split into subcomponents and keep the public API small.

---

## Telemetry
Log:
- skill: `frontend/component-scaffold`
- files_touched
- conventions_source: `repo_profile | inferred | user_specified`
- outcome: `success | partial | blocked`

Overview

This skill creates a new UI component that matches the project's conventions for file layout, typing, styling, and exports. It produces minimal, predictable component code, wires exports to existing barrels if required, and adds only the usage artifacts the repo pattern mandates. The goal is fast, convention-driven scaffolding without changing APIs or implementing domain logic.

How this skill works

The skill reads the repository profile (REPO_PROFILE.json) when available, or infers conventions from nearby components. It selects the correct placement, generates a small typed component with sane defaults, and wires exports and minimal examples only if the project's patterns require them. It then runs configured validations (typecheck and simple render smoke tests) and reports touched files and outcome.

When to use it

  • Adding a new presentational or container UI component consistent with project conventions
  • Extending a feature area or component library with a small, typed component
  • Bootstrapping components during feature development while preserving export patterns
  • When you want automated, repeatable placement and wiring of component files
  • When repo conventions must be respected (file naming, styling, barrel exports)

Best practices

  • Provide a concise responsibility statement (1–2 sentences) and a small, stable props surface
  • List props with types when known; prefer sensible defaults and optional props over broad APIs
  • Point to existing design-system components or styles the new component should reuse
  • Keep the component focused; split large concerns into private subcomponents
  • If conventions are unclear, ask targeted questions about framework, naming, and export pattern before generating files

Example use cases

  • Create a Button component in the shared components folder that follows the library’s TypeScript and styling rules
  • Add a SettingsToggle to a feature folder with minimal props and a demo story if stories are required
  • Scaffold a Card component near similar components so the new file reuses local style modules and barrel export patterns
  • Add a small form field component that composes an existing design-system Input and is exported through the feature index

FAQ

What inputs do I need to provide?

Supply component name, target location, a 1–2 sentence responsibility statement, props (names and types if known), and any dependencies on existing components or design system pieces.

Will this change existing APIs or perform large refactors?

No. The skill intentionally avoids changing API contracts or performing unrelated refactors; it creates only the component files and minimal wiring required by conventions.