asc-app-shots

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

asc-app-shots: App Store Screenshot Generator

asc-app-shots: App Store截图生成工具

Two workflows for creating App Store screenshots:

	Workflow A: AI (Gemini)	Workflow B: HTML (Deterministic)
Plan format	`ScreenPlan` (app-shots-plan.json)	`CompositionPlan` (composition-plan.json)
Command	`asc app-shots generate`	`asc app-shots html`
Output	PNG files via Gemini	Self-contained HTML with export
Mockup	AI-rendered device frame	Real PNG mockup frame (bundled)
Reproducible	No (AI varies each run)	Yes (same plan = same output)
Requires API key	Yes (Gemini)	No
Multi-device	One per screen	Multiple per screen

创建App Store截图的两种工作流：

	工作流A：AI驱动（Gemini）	工作流B：基于HTML的确定型
方案格式	`ScreenPlan` （app-shots-plan.json）	`CompositionPlan` （composition-plan.json）
命令	`asc app-shots generate`	`asc app-shots html`
输出结果	通过Gemini生成PNG文件	可独立运行的HTML页面（支持导出）
样机框架	AI渲染的设备框架	内置的真实PNG样机框架
可复现性	否（每次AI生成结果不同）	是（相同方案生成相同输出）
是否需要API密钥	是（Gemini）	否
多设备支持	单屏一个设备	单屏多个设备

Workflow B — HTML-based (Deterministic)

工作流B — 基于HTML的确定型

Use this when the user wants precise control, reproducibility, or no AI dependency.

当用户需要精准控制、可复现结果或不依赖AI时使用此工作流。

Step 1 — Write a CompositionPlan

步骤1 — 编写CompositionPlan

See

references/composition-plan-schema.md

for the full schema.

The CompositionPlan uses normalized 0–1 coordinates so the same plan works at any resolution.

json

{
  "appName": "MyApp",
  "canvas": { "width": 1320, "height": 2868, "displayType": "APP_IPHONE_69" },
  "defaults": {
    "background": { "type": "gradient", "from": "#2A1B5E", "to": "#000000", "angle": 180 },
    "textColor": "#FFFFFF",
    "subtextColor": "#A8B8D0",
    "accentColor": "#4A7CFF",
    "font": "Inter"
  },
  "screens": [
    {
      "texts": [
        { "content": "APP MANAGEMENT", "x": 0.065, "y": 0.028, "fontSize": 0.028, "fontWeight": 700, "color": "#B8A0FF" },
        { "content": "All your apps,\none dashboard.", "x": 0.065, "y": 0.055, "fontSize": 0.075, "fontWeight": 800, "color": "#FFFFFF" }
      ],
      "devices": [
        { "screenshotFile": "screenshot-1.png", "mockup": "iPhone 17 Pro Max", "x": 0.5, "y": 0.65, "scale": 0.88 }
      ]
    }
  ]
}

完整的方案架构请参考

references/composition-plan-schema.md

。

CompositionPlan采用0–1标准化坐标，因此同一方案可适配任意分辨率。

json

{
  "appName": "MyApp",
  "canvas": { "width": 1320, "height": 2868, "displayType": "APP_IPHONE_69" },
  "defaults": {
    "background": { "type": "gradient", "from": "#2A1B5E", "to": "#000000", "angle": 180 },
    "textColor": "#FFFFFF",
    "subtextColor": "#A8B8D0",
    "accentColor": "#4A7CFF",
    "font": "Inter"
  },
  "screens": [
    {
      "texts": [
        { "content": "APP MANAGEMENT", "x": 0.065, "y": 0.028, "fontSize": 0.028, "fontWeight": 700, "color": "#B8A0FF" },
        { "content": "All your apps,\none dashboard.", "x": 0.065, "y": 0.055, "fontSize": 0.075, "fontWeight": 800, "color": "#FFFFFF" }
      ],
      "devices": [
        { "screenshotFile": "screenshot-1.png", "mockup": "iPhone 17 Pro Max", "x": 0.5, "y": 0.65, "scale": 0.88 }
      ]
    }
  ]
}

Design patterns (Helm / premium App Store style)

设计模式（Helm/高级App Store风格）

Follow these patterns for professional-looking screenshots:

Single device screen:

Small uppercase category label at top:
```
y: 0.028
```
,
```
fontSize: 0.028
```
, colored to match gradient
Bold 2-line heading below:
```
y: 0.055
```
,
```
fontSize: 0.075
```
,
```
fontWeight: 800
```
, white
Large phone:
```
scale: 0.88
```
,
```
y: 0.65
```
— fills space below text, overflows bottom
Each screen gets a unique gradient vibe (purple, blue, teal) fading to black

Two-device screen:

Center-aligned text:
```
x: 0.5
```
,
```
textAlign: "center"
```
Back phone:
```
x: 0.34
```
,
```
y: 0.58
```
,
```
scale: 0.50
```
Front phone:
```
x: 0.66
```
,
```
y: 0.64
```
,
```
scale: 0.50
```
Front phone rendered on top (listed second in
```
devices
```
array)

Color vibes (each screen different):

Purple:

{ "from": "#2A1B5E", "to": "#000000" }

with label

#B8A0FF

Blue:

{ "from": "#1B3A5E", "to": "#000000" }

with label

#7BC4FF

Teal:

{ "from": "#1A4A3E", "to": "#000000" }

with label

#7BFFC4

遵循以下模式可制作具有专业质感的截图：

单设备截图布局：

顶部添加小型大写分类标签：
```
y: 0.028
```
，
```
fontSize: 0.028
```
，颜色与渐变背景匹配
标签下方添加加粗两行标题：
```
y: 0.055
```
，
```
fontSize: 0.075
```
，
```
fontWeight: 800
```
，白色
大型手机：
```
scale: 0.88
```
，
```
y: 0.65
```
— 填充文本下方空间，底部超出画布
每个截图使用独特的渐变色调（紫色、蓝色、青绿色），最终过渡到黑色

双设备截图布局：

文本居中对齐：
```
x: 0.5
```
，
```
textAlign: "center"
```
后置手机：
```
x: 0.34
```
，
```
y: 0.58
```
，
```
scale: 0.50
```
前置手机：
```
x: 0.66
```
，
```
y: 0.64
```
，
```
scale: 0.50
```
前置手机渲染在上方（在
```
devices
```
数组中排在第二位）

色调参考（每个截图使用不同色调）：

紫色：

{ "from": "#2A1B5E", "to": "#000000" }

，标签色

#B8A0FF

蓝色：

{ "from": "#1B3A5E", "to": "#000000" }

，标签色

#7BC4FF

青绿色：

{ "from": "#1A4A3E", "to": "#000000" }

，标签色

#7BFFC4

Step 2 — Run html command

步骤2 — 运行html命令

bash

undefined

bash

undefined

Auto-discover screenshots from plan directory

自动从方案目录中识别截图

asc app-shots html --plan composition-plan.json --output-dir output

Explicit screenshot paths

指定截图路径

asc app-shots html --plan composition-plan.json --output-dir output screenshot-1.png screenshot-2.png

Disable mockup frame (screenshots only, no device frame)

禁用样机框架（仅显示截图，无设备边框）

asc app-shots html --plan composition-plan.json --output-dir output --mockup none


The command auto-detects the plan format (CompositionPlan vs ScreenPlan).

Output: a single `app-shots.html` file with:
- All screenshots embedded as base64 data URIs
- Real device mockup frame (bundled iPhone 17 Pro Max - Deep Blue by default)
- Client-side PNG export via html-to-image CDN
- "Export All" button to download each screen as a PNG

asc app-shots html --plan composition-plan.json --output-dir output --mockup none


命令会自动识别方案格式（CompositionPlan或ScreenPlan）。

输出结果：单个`app-shots.html`文件，包含：
- 所有截图以base64数据URI形式嵌入
- 真实设备样机框架（默认内置iPhone 17 Pro Max - 深海蓝）
- 通过html-to-image CDN实现客户端PNG导出
- “导出全部”按钮，可将每个截图下载为PNG文件

Device mockup system

设备样机系统

The bundled default is iPhone 17 Pro Max - Deep Blue (

mockups.json

). Users can:

Use the default: omit
```
--mockup
```
Disable:
```
--mockup none
```

Use custom PNG:

--mockup /path/to/frame.png --screen-inset-x 80 --screen-inset-y 70

Add custom mockups: place
```
mockups.json
```
+ PNG files in
```
~/.asc/mockups/
```

The

mockup

field in each device slot refers to a device name in

mockups.json

json

{
  "iPhone 17 Pro Max - Deep Blue": {
    "category": "iPhone",
    "model": "iPhone 17 Pro Max",
    "displayType": "APP_IPHONE_67",
    "outputWidth": 1470, "outputHeight": 3000,
    "screenInsetX": 75, "screenInsetY": 66,
    "file": "iPhone 17 Pro Max - Deep Blue - Portrait.png",
    "default": true
  }
}

默认内置的样机为iPhone 17 Pro Max - 深海蓝（配置在

mockups.json

中）。用户可：

使用默认样机：省略
```
--mockup
```
参数
禁用样机：
```
--mockup none
```

使用自定义PNG样机：

--mockup /path/to/frame.png --screen-inset-x 80 --screen-inset-y 70

添加自定义样机：将
```
mockups.json
```
及PNG文件放入
```
~/.asc/mockups/
```
目录

每个设备插槽中的

mockup

字段对应

mockups.json

中的设备名称：

json

{
  "iPhone 17 Pro Max - Deep Blue": {
    "category": "iPhone",
    "model": "iPhone 17 Pro Max",
    "displayType": "APP_IPHONE_67",
    "outputWidth": 1470, "outputHeight": 3000,
    "screenInsetX": 75, "screenInsetY": 66,
    "file": "iPhone 17 Pro Max - Deep Blue - Portrait.png",
    "default": true
  }
}

HTML command flags

HTML命令参数

Flag	Default	Description
`--plan`	`.asc/app-shots/app-shots-plan.json`	Path to plan JSON
`--output-dir`	`.asc/app-shots/output`	Output directory
`--output-width`	`1320`	Canvas width (overridden by plan's `canvas.width` )
`--output-height`	`2868`	Canvas height (overridden by plan's `canvas.height` )
`--device-type`	—	Named device type, overrides width/height
`--mockup`	(bundled default)	Device name, file path, or `"none"`
`--screen-inset-x`	—	Override screen inset X from mockups.json
`--screen-inset-y`	—	Override screen inset Y from mockups.json

参数	默认值	描述
`--plan`	`.asc/app-shots/app-shots-plan.json`	方案JSON文件路径
`--output-dir`	`.asc/app-shots/output`	输出目录
`--output-width`	`1320`	画布宽度（会被方案中的 `canvas.width` 覆盖）
`--output-height`	`2868`	画布高度（会被方案中的 `canvas.height` 覆盖）
`--device-type`	—	指定设备类型，会覆盖宽度/高度设置
`--mockup`	(内置默认值)	设备名称、文件路径或 `"none"`
`--screen-inset-x`	—	覆盖 `mockups.json` 中的屏幕X轴内边距
`--screen-inset-y`	—	覆盖 `mockups.json` 中的屏幕Y轴内边距

Workflow A — AI-powered (Gemini)

工作流A — AI驱动型（Gemini）

Three-step workflow:

This skill — fetch metadata + analyze screenshots → write
```
app-shots-plan.json
```
asc app-shots generate
— read plan + call Gemini image generation → output
```
screen-{n}.png
```
asc app-shots translate
(optional) — translate generated screenshots into other locales

三步工作流：

本技能 — 获取元数据+分析截图 → 生成
```
app-shots-plan.json
```
文件
asc app-shots generate
— 读取方案+调用Gemini图像生成 → 输出
```
screen-{n}.png
```
asc app-shots translate
（可选） — 将生成的截图翻译为其他语言版本

Step 1 — Detect CLI command

步骤1 — 检测CLI命令

bash

which asc

If found → use
```
asc
```
directly
If not found → use
```
swift run asc
```

bash

which asc

若找到 → 直接使用
```
asc
```
命令
若未找到 → 使用
```
swift run asc
```
命令

Step 2 — Gather inputs

步骤2 — 收集输入信息

See project-context.md for the app ID resolution order.

App ID — read from
```
.asc/project.json
```
first; if not present, run
```
asc apps list
```
Version ID — run
```
asc versions list --app-id <APP_ID>
```
and use the first result
Locale — default:
```
en-US
```
Screenshot files — check
```
.asc/app-shots/
```
first; only ask user if no files found

应用ID的优先级顺序请参考project-context.md。

应用ID — 优先从
```
.asc/project.json
```
读取；若不存在，运行
```
asc apps list
```
获取
版本ID — 运行
```
asc versions list --app-id <APP_ID>
```
，使用第一个结果
语言区域 — 默认：
```
en-US
```
截图文件 — 优先检查
```
.asc/app-shots/
```
目录；仅当未找到文件时询问用户

Step 3 — Fetch App Store metadata

步骤3 — 获取App Store元数据

See

references/commands.md

for the full command reference.

bash

APP_INFO_ID=$(asc app-infos list --app-id <APP_ID> | jq -r '.data[0].id')
asc app-info-localizations list --app-info-id "$APP_INFO_ID" \
  | jq '.data[] | select(.locale == "<LOCALE>") | {name, subtitle}'

VERSION_ID=$(asc versions list --app-id <APP_ID> | jq -r '.data[0].id')
asc version-localizations list --version-id "$VERSION_ID" \
  | jq '.data[] | select(.locale == "<LOCALE>") | {description, keywords}'

Summarize

description

to 2-3 sentences (≤200 chars) for

appDescription

完整命令参考请见

references/commands.md

。

bash

APP_INFO_ID=$(asc app-infos list --app-id <APP_ID> | jq -r '.data[0].id')
asc app-info-localizations list --app-info-id "$APP_INFO_ID" \
  | jq '.data[] | select(.locale == "<LOCALE>") | {name, subtitle}'

VERSION_ID=$(asc versions list --app-id <APP_ID> | jq -r '.data[0].id')
asc version-localizations list --version-id "$VERSION_ID" \
  | jq '.data[] | select(.locale == "<LOCALE>") | {description, keywords}'

将

description

总结为2-3句话（≤200字符），填入

appDescription

字段。

Step 4 — Analyze screenshots with vision

步骤4 — 使用视觉工具分析截图

Read each screenshot file. Extract:

Colors: primary, accent, text, subtext hex values
Per-screen: heading (2-5 words), subheading (6-12 words), layoutMode, visualDirection, imagePrompt
Tone: minimal / playful / professional / bold / elegant

See

references/plan-schema.md

for the full ScreenPlan schema and imagePrompt formula.

读取每个截图文件，提取以下信息：

颜色：主色、强调色、文本色、次要文本色的十六进制值
单屏信息：标题（2-5个词）、副标题（6-12个词）、布局模式、视觉方向、图像提示词
风格基调：极简/活泼/专业/醒目/优雅

完整的ScreenPlan架构及图像提示词规则请参考

references/plan-schema.md

。

Step 5 — Write plan and generate

步骤5 — 生成方案并执行截图生成

Write to

.asc/app-shots/app-shots-plan.json

, then immediately run:

bash

asc app-shots generate

Gemini API key resolution:

--gemini-api-key

→

$GEMINI_API_KEY

→

~/.asc/app-shots-config.json

将内容写入

.asc/app-shots/app-shots-plan.json

，然后立即运行：

bash

asc app-shots generate

Gemini API密钥的优先级：

--gemini-api-key

参数 →

$GEMINI_API_KEY

环境变量 →

~/.asc/app-shots-config.json

配置文件

Step 6 — Translate (optional)

步骤6 — 翻译（可选）

bash

asc app-shots translate --to zh --to ja

See

references/commands.md

for all translate flags.

bash

asc app-shots translate --to zh --to ja

所有翻译参数请参考

references/commands.md

。

Gemini API key management

Gemini API密钥管理

bash

asc app-shots config --gemini-api-key AIzaSy...    # save key
asc app-shots config                                # show current key (masked) + source
asc app-shots config --remove                       # delete saved key

bash

asc app-shots config --gemini-api-key AIzaSy...    # 保存密钥
asc app-shots config                                # 显示当前密钥（掩码处理）及来源
asc app-shots config --remove                       # 删除已保存的密钥