nextjs-shadcn

Next.js + shadcn/ui

构建与内容、受众和任务相契合的界面视觉形象。以下是设计默认原则，并非固定的页面模板；应优先遵循用户的指引和既有设计系统。

选择视觉方向

对于新视图或大幅改版，先使用 frontend-design 选择字体、配色和构图，再开始构建。小幅修改时，保留现有且可正常使用的视觉系统。

根据产品调性、阅读密度和语言支持情况选择字体。使用 shadcn/create 一并选择组件样式、正文和标题字体、图标系列及主题。用有代表性的内容对照预览，再审慎确定字体比例、间距和层级。默认预设或不寻常的字体都不能保证设计效果出色。

在项目设计说明中记录所选预设、主题、字体和图标系列；除非设计需求发生变化，否则应保持这一方向。参考资料和图片因项目而异。组件样式与图标系列是两项独立选择；styling.md 对此有详细说明。

确保用户的任务清晰：

• 删除装饰性徽章、重复标题、空洞的营销宣传语，以及解释显而易见事项的辅助文本。
• 保留有用的状态信息、导航、说明和披露内容。
• 仅在内容需要时使用卡片、分区和 CTA，不要为了填充模板而添加它们。
• 使用简短动效，让操作与其结果、展开的详情或当前导航项产生关联。复用现有交互组件；styling.md 介绍了 Motion、GSAP 和 vercel-react-view-transitions，适用于不同的动画需求。
• 复用项目的图标系列。需要新的 UI 图标、文件类型图标或官方品牌素材时使用 icons；图标不能自动取代清晰的文字标签。

适当营造氛围

网格和点阵图案、柔和的背景光效、渐变、自定义形状、纹理、插画和视频都是可用的设计工具。若符合设计需求、能强化产品形象或让页面分区更清晰，就可以使用。独特的背景可能是正确的选择；页面也可能过于单调。

将效果置于内容后方，使其与配色保持一致，并注意与页面比例协调。若定制媒体能改善效果，请使用现有的图像或视频生成工具；也可以复用合适的真实素材。根据任务选择素材和实现方式；没有强制使用的动画库，也没有图片数量限制。

选择字体、自定义主题、背景、媒体或动效时，请阅读 styling.md。

基于实际项目开展工作

新项目中使用 Bun 管理包和脚本：bun install、bun add、bun run <script> 和 bunx --bun <cli>。这是用户的默认选择；无需再次询问用户要使用哪种包管理器。现有项目则应遵循 packageManager、锁文件、组件约定和已配置的别名。

编辑前检查 components.json 和已安装的组件。使用 shadcn 技能以及 CLI 的 info/docs 命令，了解项目元数据、组件文档和注册表指南。

组件 API 取决于底层原语（init --base base|radix|aria；默认使用 Base UI）：Base UI 使用 render，而 Radix 通常使用 asChild。保留现有的底层原语，并查阅其文档。

shadcn docs、add 和 view 需要通过网络访问注册表；docs 返回的是 URL，而非文本。离线时，项目自身的 components/ui 源码和原语包的类型定义可作为 API 参考；shadcn <command> --help、preset decode、migrate --list 和已安装的 shadcn/tailwind.css 仍可使用。

优先查阅与已安装 Next.js 版本相匹配的文档，包括存在时的 node_modules/next/dist/docs/。使用可用的 Next.js 开发工具查看运行时错误和路由上下文，而不要依赖记忆中的 API。

保持集成稳健

• 尽可能缩小客户端组件的边界；提供程序和交互式子树可能需要更高层级的边界。
• 将共享界面元素放在布局中，将路由内容放在对应路由附近。(protected) 路由组不会强制执行授权。
• 在 Server Actions 和数据访问中进行身份验证、授权和验证。根据数据新鲜度和访问要求选择缓存策略。
• 使用语义化主题令牌和现有组件变体。有意进行的设计系统调整应放在主题或组件定义中。

阅读 architecture.md，了解路由、Server/Client 边界和缓存；阅读 sidebar.md，了解共享侧边栏布局；阅读 project-setup.md，了解脚手架和预设。

验证结果

在相关的移动端和桌面端宽度下检查渲染效果。检查布局、换行、溢出、控件以及此次更改影响的状态。保持无障碍性、焦点和减少动态效果行为；截图和 DOM 检查回答的是不同问题。确保视觉效果完善：将实际视图和动画中间状态与项目的设计方向进行对比，并在交付前修复发现的问题。

运行项目的检查。如果已配置 @shadcn/lint，请利用其反馈保持设计系统一致。对于新的 Tailwind v4 项目，或反复出现的主题偏差，可考虑将其集成到现有的代码检查工具中。根据预期设计配置规则；自定义背景和媒体可能需要有意设置例外。参阅 shadcn-platform.md，了解代码检查设置和可选的 shadcn 工具。

报告更改内容和验证情况。