Next.js + shadcn/ui
Build an interface with a visual identity that fits its content, audience and task. These are design defaults, not a fixed page recipe; the user's direction and an established design system take precedence.
Choose the visual direction
For a new view or substantial redesign, use frontend-design to choose the typography, palette and composition before building. Preserve a working visual system during smaller edits.
Choose fonts for the product's tone, reading density and language support. Use shadcn/create to choose the component style, body and heading fonts, icon family and theme together. Compare the preview with representative content, then make deliberate choices about type scale, spacing and hierarchy. Neither the default preset nor an unusual font guarantees a good design.
Record the chosen preset, theme, fonts and icon family in the project's design notes; preserve that direction unless the brief changes. References and images are project-specific. Component style and icon family are separate choices; styling.md [blocked] covers them.
Keep the user's task clear:
- Cut decorative badges, repeated headings, empty marketing claims and helper text that explains the obvious.
- Keep useful status, navigation, explanations and disclosures.
- Use cards, sections and CTAs because the content needs them, rather than filling a template.
- Use brief motion to connect an action with its result, expanded details or active navigation. Reuse existing interaction components; styling.md [blocked] covers Motion, GSAP and
vercel-react-view-transitionsfor different animation needs. - Reuse the project's icon family. Use
iconswhen sourcing new UI icons, file-type icons or official brand assets; an icon does not automatically replace a clear label.
Use atmosphere when it helps
Grid and dot patterns, soft background lights, gradients, custom shapes, textures, illustrations and video are available design tools. Use them when they suit the brief, strengthen the product's identity or clarify a section. A distinctive background can be the right choice; a quiet page can be too.
Keep effects behind content, consistent with the palette and proportionate to the page. Use available image or video generation tools when purpose-made media would improve the result, or reuse suitable real assets. Choose the asset and implementation for the task; there is no mandatory animation library or image quota.
Read styling.md [blocked] when deciding on fonts, theme customization, backgrounds, media or motion.
Work from the actual project
Use Bun for packages and scripts in new projects: bun install, bun add, bun run <script> and bunx --bun <cli>. This is the user's default; do not ask them to choose a package manager again. In existing projects, follow packageManager, the lockfile, component conventions and configured aliases.
Inspect components.json and the installed components before editing. Use the shadcn skill and the CLI's info/docs commands for project metadata, component documentation and registry guidance.
Component APIs depend on the primitive base (init --base base|radix|aria; Base UI is the default): Base UI uses render where Radix commonly uses asChild. Preserve the existing base and consult its docs.
shadcn docs, add and view need the registry over the network; docs returns URLs rather than text. Offline, the project's own components/ui source and the primitive package's type definitions are the API reference, and shadcn <command> --help, preset decode, migrate --list and the installed shadcn/tailwind.css still work.
Prefer documentation matching the installed Next.js version, including node_modules/next/dist/docs/ when present. Use available Next.js dev tools for runtime errors and route context rather than relying on remembered APIs.
Keep the integration sound
- Keep Client Component boundaries as narrow as practical; providers and interactive subtrees may need a higher boundary.
- Keep shared chrome in layouts and route content near its route. A
(protected)route group does not enforce authorization. - Authenticate, authorize and validate inside Server Actions and data access. Choose caching from freshness and access requirements.
- Use semantic theme tokens and existing component variants. Put deliberate design-system changes in the theme or component definitions.
Read architecture.md [blocked] for routing, Server/Client boundaries and caching; sidebar.md [blocked] for shared sidebar layouts; project-setup.md [blocked] for scaffolding and presets.
Verify the result
Inspect the rendered view at relevant mobile and desktop widths. Check composition, wrapping, overflow, controls and the states affected by the change. Preserve accessibility, focus and reduced-motion behavior; screenshots and DOM inspection answer different questions. Own the visual finish: compare the real view and animation intermediates with the project's direction, and fix observed defects before delivery.
Run the project's checks. If @shadcn/lint is configured, use its feedback to keep the design system coherent. For a new Tailwind v4 project, or recurring theme drift, consider integrating it with the existing linter. Configure rules for the intended design; custom backgrounds and media may need deliberate exceptions. See shadcn-platform.md [blocked] for lint setup and optional shadcn utilities.
Report what changed and what was verified.
