---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
license: Complete terms in LICENSE.txt
---

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.

## Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
- **Constraints**: Technical requirements (framework, performance, accessibility).
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?

**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
- Production-grade and functional
- Visually striking and memorable
- Cohesive with a clear aesthetic point-of-view
- Meticulously refined in every detail

## Frontend Aesthetics Guidelines

Focus on:
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.

NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.

Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.

**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.

---

## Delivery Pipeline（交付方式 —— 必读）

本 skill 产出的代码通常要走 `web-artifacts-builder` 打包成单文件 HTML 工件。遵守下面的约束，
生成的项目才能**被 `bundle-artifact.sh` 成功构建**。

### 交付路径选择

| 场景 | 路径 |
|---|---|
| 单页、无状态、无路由、无 shadcn 组件 | **Path A**：一份独立 `.html`（内联 CSS / JS），直接 `save_to_outputs` |
| 多组件、shadcn 风格、状态管理、表单/交互 | **Path B**：按 web-artifacts-builder 项目结构产出源文件 |

> 不确定时默认 **Path A**。只有用户明确要 SPA、仪表盘、多页切换，或提到 shadcn/ui 时才走 Path B。

### Path A —— Stand-alone HTML

产出单个 `index.html`，所有 CSS 写在 `<style>`，所有 JS（含 React CDN）写在 `<script>`。
适合海报、landing page、presentation。写入 `/outputs/<name>.html` 后，
前端会当 `text/html` artifact 展示。

**允许使用**：任意 CDN 资源（Google Fonts / unpkg / esm.sh），因为运行环境是用户浏览器，浏览器有网。

### Path B —— web-artifacts-builder 项目（关键约束）

沙箱镜像已内置**预构建的 Vite + React + Tailwind + 40+ shadcn/ui + Parcel 项目模板**
（位于 `/opt/vite-react-shadcn-template/`，node_modules 已完整安装）。LLM 不需要也不能跑
`pnpm create vite` / `pnpm install`（沙箱无网）。用两个自带的包装器：

- `web-artifacts-init <project-name>`：秒级从模板复制一个新项目到当前目录
- `web-artifacts-bundle`：在项目目录里跑 Parcel + html-inline，输出 `bundle.html`

典型交付代码开头就这样写：

```python
import subprocess, os
os.chdir('/work')
subprocess.run(['web-artifacts-init', 'my-artifact'], check=True)
os.chdir('/work/my-artifact')
# —— 接下来用 open(...).write(...) 往 src/ 下写你的 tsx/css 源文件 ——
# ... 写完后 ...
subprocess.run(['web-artifacts-bundle'], check=True)
# 产物就是当前目录下的 bundle.html；把它复制到 /outputs 让大龙虾回落成 Artifact
import shutil
shutil.copy('bundle.html', '/outputs/my-artifact.html')
```

只负责往 `src/` 下写 `.tsx` / `.ts` / `.css` 源文件。最终由 `web-artifacts-bundle` 打成
`bundle.html`。

#### 生成的目录结构

只产出/修改这些位置的文件，**不要**动 `package.json` / `vite.config.ts` / `index.html` / `main.tsx` / `tsconfig*.json`：

```
<project>/
├── src/
│   ├── App.tsx                ← 主要编辑点；默认导出根组件 <App />
│   ├── index.css              ← 可追加 @font-face / custom utilities，保留顶部 @tailwind 三行
│   ├── components/            ← 业务组件新建在这里
│   │   └── <YourComponent>.tsx
│   ├── lib/utils.ts           ← 已存在，导出 cn()；不要覆盖
│   └── hooks/                 ← 自定义 hook 放这里
```

**绝对禁止新建**：`next.config.js` / `.env*` / `server/` / `app/` / 任何 Next.js 特有目录。

#### Import 路径规范（Parcel + tspaths 依赖的硬约束）

| 目标 | 写法 |
|---|---|
| shadcn/ui 组件 | `import { Button } from "@/components/ui/button"` |
| shadcn/ui 组件（复合） | `import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"` |
| cn 工具 | `import { cn } from "@/lib/utils"` |
| 自己写的组件 | `import { MyThing } from "@/components/MyThing"` |
| 自己的 hook | `import { useMyHook } from "@/hooks/useMyHook"` |
| 图标 | `import { ChevronRight, Zap } from "lucide-react"` |
| React | `import { useState, useEffect } from "react"` |

**绝对禁止**：
- 相对路径爬出 `src/`：~~`../../lib/utils`~~
- 默认导入 shadcn 组件：~~`import Button from "@/components/ui/button"`~~（它们是具名导出）
- Next.js 专属：~~`next/image` / `next/link` / `'use client'` / `'use server'`~~
- Node API：`fs` / `path` / `process.env`（浏览器环境没有）
- `import.meta.hot` / `import.meta.env` 之类 Vite 专属（Parcel 不识别）

#### 可用的依赖清单（骨架已安装，直接 import）

- **React 18**：`react` / `react-dom`
- **shadcn/ui**：40+ 组件在 `@/components/ui/`（accordion / alert / aspect-ratio / avatar / badge / breadcrumb / button / calendar / card / carousel / checkbox / collapsible / command / context-menu / dialog / drawer / dropdown-menu / form / hover-card / input / label / menubar / navigation-menu / popover / progress / radio-group / resizable / scroll-area / select / separator / sheet / skeleton / slider / sonner / switch / table / tabs / textarea / toast / toggle / toggle-group / tooltip）
- **样式工具**：`clsx` / `tailwind-merge` / `class-variance-authority` / `tailwindcss-animate`
- **图标**：`lucide-react`
- **主题**：`next-themes`（放心用，不是 Next 框架）
- **表单**：`react-hook-form` + `@hookform/resolvers` + `zod`
- **日期**：`date-fns` + `react-day-picker`
- **交互**：`sonner` (toast) / `cmdk` (command palette) / `vaul` (drawer) / `embla-carousel-react` / `react-resizable-panels`

**不在骨架里的常用库**（如需使用必须向用户说明）：
- `framer-motion` / `motion`：未装。优先用 CSS 动画 + `tailwindcss-animate`；非要 JS 动画可自写 IntersectionObserver + `transition` 类。
- `recharts` / `d3` / `three.js`：未装。需要图表时用 `<svg>` 手写。
- 任何其他 npm 包：**不要** `pnpm add`——会触发网络请求，沙箱无网会失败。

#### CSS 规范

1. **主题色一律走 shadcn CSS 变量**，不要硬编码十六进制色值：
   - `bg-background` / `bg-card` / `bg-primary` / `bg-secondary` / `bg-muted` / `bg-accent` / `bg-destructive`
   - `text-foreground` / `text-muted-foreground` / `text-primary` / `text-primary-foreground`
   - `border-border` / `border-input` / `ring-ring`
   - 暗色主题切换 `next-themes` 会自动处理；只要用变量就不会坏
2. **字体**：在 `src/index.css` 顶部（`@tailwind` 三行之前或之后任意位置）追加 `@import url('https://fonts.googleapis.com/...')`。运行时用户浏览器取字体，没问题。**不要**下载 ttf 到仓库里。
3. **动画**：优先 Tailwind utility（`transition-all` / `duration-*` / `ease-*`）+ CSS keyframes（在 `tailwind.config.js` 的 keyframes/animation 里加也行，但更简单的做法是写在 `src/index.css` 的 `@layer utilities`）。
4. **暗色样式**：`dark:bg-slate-900` 之类可以加，但更推荐用变量（变量已处理明暗切换）。

#### 图片 / 字体 / 媒体

`bundle-artifact.sh` 用 `html-inline` 把最终 HTML 里所有引用的资源 inline。约束：
- **图片**：优先用 inline SVG 或 `<svg>` 代码，最保险。退而求其次用 `data:image/...;base64,...`。**不要** `<img src="/public/foo.png">` —— 骨架没有 public 目录。
- **远程图片**（https://images.unsplash.com 等）：**可以**，html-inline 会尝试抓取；但政务内网构建环境可能无公网，运行时在浏览器加载则没问题 —— 选一个。
- **字体文件**：只走 CDN `@import`。不要上传 `.woff2` 到 src。

#### 交付清单（Path B 生成代码时必须同时给出）

产出物包含两部分：
1. 每个新建/修改文件的**完整**内容（不要 `// ... unchanged` 省略）
2. 构建指令，走镜像内置的离线工具：
   ```bash
   cd /work
   web-artifacts-init my-artifact
   cd my-artifact
   # 这里把上面每一份文件内容写到对应的 src/... 路径
   web-artifacts-bundle                      # 产物 bundle.html
   cp bundle.html /outputs/my-artifact.html  # 让大龙虾回落成 Artifact
   ```

**不要**调 `bash /skill/web-artifacts-builder/scripts/init-artifact.sh`——它依赖
`pnpm create vite` 的网络下载，沙箱里 `--network none` 会卡死。永远用 `web-artifacts-init`.

#### 构建前自查（生成代码后逐条过一遍）

- [ ] 根组件 `src/App.tsx` 存在，且默认导出 `export default function App() { ... }`
- [ ] 所有自写组件 import 用 `@/` 别名，**没有**向上相对路径
- [ ] 没有任何 `pnpm add` 指令 —— 只用白名单里的依赖
- [ ] 没有 `next/*` / `'use client'` / `import.meta.env`
- [ ] 颜色用 shadcn 变量而不是 `#rgb`
- [ ] 外部字体走 `@import url(...)`，没有 `.woff2` 文件引用
- [ ] 不依赖 `framer-motion` / `recharts` / `three` 等未装库（若必需，明确告诉用户）
- [ ] 组件 JSX 里所有 shadcn 组件都按具名导出 import：`import { Button } from "@/components/ui/button"`
- [ ] 检查所有 JS/JSX/TSX 字符串里的引号嵌套，尤其是中文内容中包裹短语的引号：不要在 `"..."` 里直接写未转义的 `"`，也不要在 `'...'` 里直接写未转义的 `'`，例如 `text: "从"信息孤岛"走向"智能分发"时代"` 会触发 `SyntaxError: Unexpected identifier`；改用反引号模板字符串、中文弯引号，或写成 `\"信息孤岛\"` / `\"智能分发\"`

满足以上全部，`bash bundle-artifact.sh` 才能跑通。

---

Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.