stitch-shadcn-ui

Stitch's shadcn/ui migration

Quick start

1. "Migrate the appointment form to shadcn Input/Button; first provide a local reviewable result."
2. "Migrate the order details Dialog and preserve keyboard behavior; preserve the existing scope and source."
3. "Compare the registry source with the existing theme tokens; mark the missing inputs and validation states."

For designers, frontend developers, and teams maintaining this workflow. Designers provide intent and materials, developers provide engineering/tooling, and the team preserves source and acceptance status during handoff.

Capability boundaries

✅ Good at handling

• Migrate the appointment form to shadcn Input/Button.
• Migrate the order details Dialog and preserve keyboard behavior.
• Compare the registry source with the existing theme tokens.

⚠️ Requires materials

• Target project and components.json.
• Stitch assets and current component behavior.
• Tailwind/React versions and the scope to be migrated.

❌ Inapplicable scenarios and handoff

• Generic React page conversion → stitch-react-components.
• Native App → stitch-react-native.
• Business login or payment services → project interface workflow, submit the form behavior contract.

Workflow

1. Read the current project version and the Stitch HTML/screenshots, and clarify the components to be migrated only.
2. Read migration-guide first, and check the original Props, state, keyboard, and theme.
3. Search the currently available registry tools and component sources, review dependencies and changes, then apply.
4. Migrate one component according to the existing cn/cva/theme conventions and preserve accessibility, then handle the next one after validation.
5. Run the target type/lint/build and keyboard/theme checks; verify-setup.sh is only a Tailwind3 heuristic and does not mean Tailwind4 or that everything passes.

Order by dependency: source verification → local artifact → authorized external operations → validation handoff. For multiple tasks, do the current main path first; if information is missing, first output an assumption draft, then precisely list what is missing and its purpose, without using vague prompts like "please provide more context."

Security and result validation

Do not read unrelated account configurations, do not collect user passwords; credentials are provided only by the environment or authorized connectors. Examples use only demo data; before uploading, replace customer names, phone numbers, and order numbers with demo values, and check the HTML, screenshots, and file metadata. It is forbidden to write keys, session cookies, base64 full text, or signed download URLs into reports/repositories. Unverified parameters, visual effects, and business figures must not be fabricated; outputs note the source, decision basis, actual execution, and parts not yet verified.

• Preserve Dialog focus restoration and keyboard close.
• Actual review of registry sources and dependencies.
• Light/dark themes and focus visibility verified.

Customizable: registry, primitives, theme, variant, target components, and migration order. Value-added checks: component-by-component migration; version branching; accessibility regression checklist.

FAQ

Q1: What is the main deliverable result? Appointment form label htmlFor="phone" + Input id="phone"; preserve error aria-describedby; do not write the phone number into the example.

Q2: When should a different entry point be used? General React page conversion → stitch-react-components; native App → stitch-react-native; business login or payment services → project interface flow, submit form behavior contract.

Q3: What happens when input is missing? First provide a clearly marked draft of local assumptions, and list "needs to be supplemented: target project and components.json; Stitch assets and current component behavior; Tailwind/React versions and migration scope". Write operations that depend on these inputs are not executed.

Q4: How is completion determined? Preserve Dialog focus restoration and keyboard closing; registry source and dependencies are actually reviewed; light/dark themes and focus visibility are verified.

Q5: How to customize? registry, primitives, theme, variant, target components, and migration order; when not provided, follow existing project values and mark assumptions.

Q6: Is upload, installation, or launch automatic? Only execute actions covered by the current request and existing authorization; without remote receipt, do not claim upload success, and without running verification, do not claim launch. Additional installation or scope expansion requires first explaining the specific impact.

Reference as needed

• When performing detailed mapping, API, or templates, read Extended workflow。
• When encountering failures/unexpected input, read Anti-patterns and Gotchas。
• When involving edge cases, compatibility, customization, and authorization, read In-depth FAQ。
• When complete input/output and verification scenarios are needed, read Local application examples。
• The local implementation basis is the source code accompanying the current skill and pinned upstream snapshot; the structure follows Agent Skills specification. The current tool behavior is subject to the actual schema; when not connected, do not claim online behavior has been verified.

When to use

Load this skill when the user needs to select and execute a verifiable, recoverable professional workflow for the current request . First extract the goal, input, constraints, delivery format, and acceptance criteria from the request; the description summary is: triggered when selecting, migrating, and verifying shadcn/ui primitives, themes, and registry content for React pages originating from Stitch. For first-time generic HTML-to-React conversion use stitch-react-components; do not automatically migrate unrelated projects..

Rules

• Read before write: first confirm the current state and real capabilities, then execute actions that change external state.
• Least privilege: use only the files, tools, accounts, and network scope required to complete the current step.
• Evidence first: when run results, resource IDs, versions, hashes, or test output are missing, clearly mark them as NOT_VERIFIED。
• Idempotency first: retain request identifiers and phase status; when results are unclear, query first and do not retry blindly.
• Privacy and security: logs, examples, receipts, and error messages must not contain tokens, cookies, keys, or personally sensitive data.

Workflow

Step 1: Clarify intent

Confirm whether this skill matches the goal; if it is only an adjacent need, hand it off to a more precise skill.

Step 2: Perform precheck

Confirm the goal, input, constraints, available tools, success criteria, and failure boundaries; if any key condition is unknown, stop at the read-only stage.

Step 3: Form a plan

List the tools to be called, the objects that will be changed, the success criteria, and the safe exit method after failure.

Step 4: Execute the action

Execute with the minimum sufficient steps, and record evidence at key state changes; for every external call, retain a traceable state or receipt.

Step 5: Verify delivery

Output the results, verification evidence, incomplete items, risks, and clear next steps, and state facts, inferences, and unverified items separately.

Validation checklist

• The skill trigger conditions are consistent with the user's intent, and adjacent tasks were not misrouted to this skill.
• The inputs, target objects, versions, and output locations are all clear, and no guessed values were used in place of required values.
• All write, payment, publishing, or irreversible actions are within the scope authorized by the user.
• The results have been verified with independent checks; "the command succeeded" or "the file exists" alone does not count as complete acceptance.
• The output includes actual evidence, failed/skipped items, remaining risks, and executable next steps.

Gotchas

1. Treating a plan as a result: A document or prompt is not equal to actual execution; the actual execution level must be indicated.
2. Retrying on error: A timeout or lost response may already have produced remote state; query first before deciding whether to retry.
3. Implicit scope expansion: Batch, full-scale, publishing, overwrite, and payment operations are not natural extensions of ordinary read/write operations.
4. Version drift: When referencing external resources, record the version, tag, or commit; do not treat a mutable branch as release evidence.
5. Stale evidence: Caches, old screenshots, and historical tests cannot prove the current environment; refresh key evidence before delivery.

Non-applicability and boundaries

Do not exceed the scope given by the user; write, payment, publishing, and irreversible actions require explicit authorization. If the request requires another skill, do not copy its body text; hand off by skill name and preserve the current task context.

Progressive disclosure

• When input/output, states, and authorization points need to be determined, read references/workflow-contract.md。
• When pre-delivery self-check is needed, read references/validation-checklist.md。
• When encountering timeouts, partial success, or recovery scenarios, read references/error-recovery.md。
• For first run, refusal of privilege escalation, and failure recovery, refer respectively to examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。