Typescript Tailwind App Builder

Workflow

Choose the stack deliberately

• Default to React + Vite + TypeScript + Tailwind for SPAs, dashboards, internal tools, prototypes, and marketing apps that do not need SSR.
• Choose Next.js App Router when the request clearly needs SSR, SEO-sensitive pages, route handlers, server actions, authentication-heavy flows, or file-based routing that materially simplifies the build.
• Preserve the repo's existing framework, package manager, lint rules, and Tailwind major version when working inside an existing app.
• Prefer current stable package releases when scaffolding a new app rather than baking stale versions into the skill. Verify version-specific setup details before assuming old Tailwind config shapes.

Set the product direction before coding

• Define the app goal, primary user, core screens, and main success path before editing files.
• Translate vague requests into a concrete screen list and component list.
• Keep the first version narrow. Build the main user journey end-to-end before expanding the feature surface.
• Pick a clear visual direction with deliberate typography, surface contrast, spacing rhythm, and accent color. Avoid generic defaults and avoid purple-by-default styling.

Scaffold with maintainability in mind

• Keep TypeScript strict enough to catch mistakes early.
• Prefer a feature-oriented src/ structure for larger apps and a flatter structure for small apps.
• Create primitives only after patterns repeat. Avoid abstracting prematurely.
• Use semantic HTML, keyboard-friendly interactions, and accessible labels by default.
• Keep dependencies lean. Add a library only when it materially reduces complexity or the repo already depends on it.

Build the UI system

• Start from reusable layout pieces: shell, section wrappers, cards, buttons, inputs, and empty states.
• Centralize reusable design tokens in CSS custom properties or the repo's existing theme layer.
• Extract repeated utility clusters into components when the same pattern appears three or more times.
• Design mobile-first, then widen layouts for tablet and desktop.
• Use motion intentionally and sparingly so transitions support hierarchy instead of distracting from content.

Build app behavior

• Model domain types explicitly instead of leaving large any gaps.
• Start with local state for local concerns.
• Introduce router, form, or data libraries only when the app complexity justifies them or the repo already uses them.
• Keep loading, empty, error, and success states visible in the UI instead of leaving TODO gaps.
• For mock data, colocate it clearly and name it as seed or demo data.

Finish like a product engineer

• Test the main path, a failure path, and the responsive layout.
• Confirm Tailwind classes stay readable and are not duplicated excessively.
• Make sure text hierarchy, contrast, spacing, and CTA placement feel intentional.
• Leave the project runnable with clear scripts and no broken imports.
• Use references/delivery-checklist.md as the final gate.

Common Defaults

• Framework: Use Vite + React unless Next.js is clearly the better fit.
• Styling: Use Tailwind plus CSS custom properties for shared tokens.
• State: Start with useState or useReducer, then reach for heavier tooling only when needed.
• Data: Stub realistic seed data when backend APIs do not exist yet.
• Forms: Validate at the edges and show inline feedback.
• Copy: Keep language short, direct, and product-like. Avoid lorem ipsum in final delivery unless explicitly requested.

Commands

Use the current package manager when the repo already defines one. For a new app, either copy the starter asset folder or scaffold from scratch with commands like:

npm create vite@latest my-app -- --template react-ts
npm install tailwindcss @tailwindcss/vite

npx create-next-app@latest my-app --ts --tailwind --eslint --app

After scaffolding, wire Tailwind using the current recommended setup for the selected framework and installed Tailwind major version rather than assuming old config shapes.

Resources

• Read references/framework-selection.md when the stack choice is not obvious.
• Read references/delivery-checklist.md before finishing any substantial build.
• Reuse assets/app-brief-template.md to translate a vague request into a concrete build plan.
• Reuse assets/vite-react-tailwind-starter as the default Vite + React + Tailwind starter template.
• Reuse assets/design-tokens.css as a starting theme layer for fresh apps.
• Reuse assets/app-shell.tsx as a responsive shell starter for React-based apps.