5.0 KiB
Reusable React Component Prompt Template
Copy this directory, rename it for the component, and customize the prompt.
Replace all <placeholders> and remove sections that do not apply.
Prompt
You are working in the fe-digitaltwin-v2 repository, a React 18 + TypeScript +
Vite application using React Router, Tailwind CSS, and shared UI libraries.
Create or update the component described below. First inspect the repository for local instructions, existing components, types, hooks, API helpers, and design patterns that can be reused. Preserve the current architecture and make the smallest complete change.
Component request
- Component name:
<PascalCaseComponentName> - Purpose:
<What the component does and why it is needed> - Target location:
src/shared/components/<category>/<ComponentName>.tsx - Used by:
<Page, route, layout, or parent component> - Reusability:
<Where it can be reused and what must remain configurable>
React composition contract
- Root element/ref:
<Element type and forwarded ref type> - Props:
<Required props, optional props, and defaults> - Controlled state:
<value/onChange pairs owned by the parent> - Uncontrolled state:
<defaultValue or internal UI-only state> - Composition:
<children, slots, render props, or subcomponents> - Native props:
<HTML attributes extended by the component> - Variants:
<Typed visual/size variants>
Keep domain data fetching, routing, and permissions in the parent unless they are the component's explicit responsibility. Prefer a controlled API for state that another component or page must observe.
Component styling theme
- Theme name:
<Short, descriptive visual direction> - Visual role:
<Quiet foundation | primary action | dense data | status surface | overlay> - Surface:
<background/card/popover/transparent> - Typography:
<Hierarchy, weight, size, and numeric treatment> - Shape:
<Radius, border, and shadow treatment> - Color:
<Semantic tokens for default, hover, active, disabled, and status> - Motion:
<Useful transitions; honor reduced motion> - Dark mode:
<How semantic tokens preserve contrast in .dark>
Use the semantic tokens documented in prompts/design-system.md. Do not hard-code
a second color system inside a reusable primitive.
UI and behavior
- Layout:
<Structure and responsive behavior> - Interactions:
<Pointer and keyboard behavior> - States:
<Default, hover, focus, active, disabled, loading, empty, error> - Accessibility:
<Role, label, focus, keyboard, and announcement behavior>
Visual reference
- Design/source:
<Screenshot, Figma link, existing component, or source-app path> - Required parity:
<Exact parity | adapt to current design system | new design> - Details that must match:
<Spacing, colors, typography, icons, dimensions, behavior>
If this is a migration from fe-front-end, treat the source implementation as
the behavior and visual reference. Translate Next.js-specific APIs to the
existing Vite/React Router equivalents; do not copy next/*, NextAuth, or
server-component assumptions into this repository.
Constraints
- Use TypeScript with explicit, reusable types; do not use
anyunless an existing external API makes it unavoidable and the reason is documented. - Use
React.forwardRefwhen consumers may need the underlying element. - Keep the public prop API small, typed, and composable.
- Allow
classNamecustomization and merge it withcn()when consistent with nearby shared primitives. - Reuse existing components and utilities before adding new abstractions.
- Prefer the established UI system nearest to the target feature. Do not mix UI libraries in one component without a repository precedent.
- Use
@/imports where they improve readability. - Keep API/data logic out of a reusable presentational component when practical.
- Do not add a dependency unless it is necessary and explicitly approved.
- Do not modify unrelated files or silently redesign neighboring UI.
- Do not expose tokens, secrets, or sensitive response data in logs or the UI.
Acceptance criteria
<Observable requirement 1><Observable requirement 2><Observable requirement 3><Loading/empty/error behavior><Responsive and accessibility behavior>
Deliverables
- Implement the component and the minimum integration needed to use it.
- Add or update types, helpers, and tests only when required by the change.
- Run focused verification that follows the repository instructions. Do not run prohibited repository-wide build/typecheck commands.
- Report:
- files changed;
- behavior implemented;
- verification performed and its result;
- assumptions or remaining limitations.
- End with a very simple, easy-to-understand TL;DR.
Do not stop at a plan when the requirements and local repository context are sufficient to implement the component. Ask a question only if a missing choice would materially change the result.