nuxt-visual-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Visual Development Workflow

可视化开发工作流

When developing or modifying any visual element (components, pages, layouts, styling), you must visually verify your work using Playwright screenshots and Compodium. Do not rely on code alone for UI changes.

当开发或修改任何视觉元素（组件、页面、布局、样式）时，你必须使用Playwright截图和Compodium对你的工作进行视觉验证。UI变更请勿仅依赖代码判断。

Setup

前置准备

Start the dev server in the background:
```
bun run dev
```
Wait for the server to be ready (listen on
```
localhost:3000
```
or the next available port)

在后台启动开发服务：
```
bun run dev
```
等待服务就绪（监听
```
localhost:3000
```
或下一个可用端口）

Verifying Pages and Layouts

验证页面与布局

Use Playwright to screenshot full pages after making changes:

bash

npx playwright screenshot --wait-for-timeout=3000 http://localhost:3000/your-page /tmp/screenshot.png

Then read the screenshot with the

Read

tool to visually inspect the result.

Always screenshot the page after each meaningful visual change (layout shifts, new sections, styling updates)
For dark mode, append
```
?dark=true
```
or toggle via the app and take a second screenshot

For responsive design, use

--viewport-size=375,812

(mobile) and

--viewport-size=1280,720

(desktop)

修改完成后使用Playwright对完整页面进行截图：

bash

npx playwright screenshot --wait-for-timeout=3000 http://localhost:3000/your-page /tmp/screenshot.png

随后使用

Read

工具读取截图，对结果进行视觉检查。

每次完成有意义的视觉变更（布局偏移、新增区块、样式更新）后，务必对页面截图
针对暗黑模式，可追加
```
?dark=true
```
参数或在应用内切换后拍摄第二张截图
针对响应式设计，使用
```
--viewport-size=375,812
```
（移动端）和
```
--viewport-size=1280,720
```
（桌面端）参数

Verifying Individual Components

验证单个组件

Use Compodium to preview components in isolation at

http://localhost:3000/__compodium__/devtools

Screenshot the Compodium renderer to inspect a specific component:

bash

npx playwright screenshot --wait-for-timeout=3000 "http://localhost:3000/__compodium__/devtools" /tmp/compodium.png

Compodium auto-discovers all components in

app/components/

— no stories needed.

使用Compodium在

http://localhost:3000/__compodium__/devtools

地址单独预览组件。

对Compodium渲染器进行截图以检查特定组件：

bash

npx playwright screenshot --wait-for-timeout=3000 "http://localhost:3000/__compodium__/devtools" /tmp/compodium.png

Compodium会自动发现

app/components/

目录下的所有组件，无需编写stories。

Iteration Loop

迭代流程

Make a visual change (template, styles, component props)
Screenshot the affected page or component
Read the screenshot to verify the result
If it doesn't look right, adjust and repeat
Only move on when the visual output matches the intent

完成视觉变更（模板、样式、组件props）
对受影响的页面或组件截图
读取截图验证结果
若不符合预期，调整后重复上述步骤
仅当视觉输出符合预期时再进入下一步

Key Flags

关键参数

Flag	Purpose
`--wait-for-timeout=3000`	Wait for hydration/rendering
`--viewport-size=375,812`	Mobile viewport
`--viewport-size=1280,720`	Desktop viewport
`--full-page`	Capture entire scrollable page
`--color-scheme dark`	Force dark color scheme

参数	用途
`--wait-for-timeout=3000`	等待水合/渲染完成
`--viewport-size=375,812`	移动端视口
`--viewport-size=1280,720`	桌面端视口
`--full-page`	捕获完整可滚动页面
`--color-scheme dark`	强制使用暗黑配色方案