appllama-design-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Appllama Design Skill

Appllama 设计技能

You are building screens that will sit on a phone next to the best-designed apps in the world. The user will compare your output to those apps within seconds of launching it. This skill defines the bar and the method for clearing it.

你正在构建的界面将与全球设计最佳的应用一同呈现在手机上，用户在启动应用后的几秒内就会将你的输出与这些应用进行对比。本技能定义了达到顶尖水准的标准与方法。

The Prime Directive: study before you draw

首要原则：先研究再设计

Never design a screen from imagination when you can study how top apps solved the same screen. Real, shipping, revenue-ranked apps encode thousands of hours of design iteration and A/B testing. Your first move on any screen is research:

If the Appllama MCP is connected, pull real screens for the category and screen type you are building (see the
```
appllama-usage
```
skill for the exact research playbooks). Study 20–30 screens before writing a line of UI code.
Extract the pattern, not the pixels: layout skeleton, information hierarchy, control choices, spacing rhythm, where the primary CTA sits, what gets an illustration vs. plain text, how progress is communicated. Note: every Appllama image and video carries a small Appllama watermark in the top-left corner. It is provenance, not design — ignore it when reading a screen (it may sit over the status bar or a back button) and never reproduce it in anything you build.
Then design your screen: same proven skeleton, your product's voice. Copying a competitor's screen 1:1 is both lazy and legally risky; shipping a screen that ignores every convention users already know is worse.

当你可以研究顶级应用如何解决同类界面问题时，绝不要凭空设计界面。真实上线、营收排名靠前的应用凝聚了数千小时的设计迭代与A/B测试。处理任何界面的第一步都是调研：

如果已连接Appllama MCP，提取你要构建的类别和界面类型对应的真实界面（具体调研指南请参考
```
appllama-usage
```
技能）。在编写任何UI代码前，先研究20–30个界面。
提取模式而非像素：布局框架、信息层级、控件选择、间距节奏、主CTA的位置、哪些内容用插图而非纯文本、进度如何传达。注意：每个Appllama的图片和视频左上角都带有一个小水印，这是来源标识而非设计元素——解读界面时请忽略它（它可能覆盖状态栏或返回按钮），且绝不要在你构建的任何内容中重现它。
然后设计你的界面：采用经过验证的框架，融入产品自身的风格。1:1复制竞品界面既偷懒又有法律风险；而忽略用户已熟知的所有惯例来设计界面则更糟糕。

Platform baseline

平台基准

Default stack assumptions (override only if the project already differs):

Expo + Expo Router, React Native, TypeScript.

react-native-reanimated

for motion,

react-native-gesture-handler

for gestures,

@shopify/flash-list

(or FlashList v2) for any list that can grow.

```
expo-image
```
for images (and SF Symbols via
```
source="sf:name"
```
on iOS),
```
expo-video
```
/
```
expo-audio
```
(never the deprecated
```
expo-av
```
).
```
react-native-safe-area-context
```
for insets. Never hard-code notch numbers.
```
process.env.EXPO_OS
```
over
```
Platform.OS
```
for compile-time platform checks.

默认技术栈假设（仅当项目已有不同配置时才覆盖）：

Expo + Expo Router、React Native、TypeScript。
使用
```
react-native-reanimated
```
实现动效，
```
react-native-gesture-handler
```
处理手势，
```
@shopify/flash-list
```
（或FlashList v2）实现可滚动列表。
使用
```
expo-image
```
加载图片（iOS端可通过
```
source="sf:name"
```
使用SF Symbols），
```
expo-video
```
/
```
expo-audio
```
（绝不要使用已废弃的
```
expo-av
```
）。
使用
```
react-native-safe-area-context
```
处理内边距。绝不要硬编码刘海屏相关数值。
编译时平台检查使用
```
process.env.EXPO_OS
```
而非
```
Platform.OS
```
。

Native fidelity laws

原生保真度准则

These are the details that separate "web page in a wrapper" from "native app". Violating any of them is a finding, not a style preference.

Semantic colors, both themes, day one. Use system/semantic color tokens (e.g.
```
Color
```
from
```
expo-router
```
on iOS:
```
Color.ios.label
```
,
```
Color.ios.secondarySystemBackground
```
; Material dynamic colors on Android). Every screen must render correctly in light AND dark before it is "done". Never pass semantic color objects into Reanimated animated styles — resolve to strings first.
Native controls over rebuilt ones. Switch, Slider, SegmentedControl, context menus, date pickers: use the native control or a faithful wrapper. A rebuilt toggle that animates 50 ms differently than iOS's reads as fake instantly.
SF Symbols / Material Symbols for iconography. On iOS prefer SF Symbols (
```
expo-image
```
with
```
sf:
```
sources, or
```
expo-symbols
```
); they inherit weight, optical size, and Dynamic Type behavior. Do not mix three icon families on one screen.
Typography is hierarchy. Use the platform type ramp (Large Title / Title / Headline / Body / Footnote on iOS). One display size per screen. Tabular numerals (
```
fontVariant: ['tabular-nums']
```
) for anything that counts, times, or prices.
```
Text selectable
```
on data users may want to copy.
Continuous corners.
```
borderCurve: 'continuous'
```
on every rounded rectangle. Squircles are the single cheapest "feels iOS" win that exists.
Shadows via CSS
boxShadow
, not legacy
```
shadow*
```
/
```
elevation
```
props. Shadows are for elevation logic, not decoration — one elevation system per app.
Spacing rhythm. Pick a base unit (4 or 8) and never leave it. Prefer flexbox
```
gap
```
over margin stacking. ScrollView padding goes in
```
contentContainerStyle
```
, never on the ScrollView itself.
Safe areas and the Dynamic Island are part of the design. Screens must be verified with content scrolled under the island / status bar (does the blur/fade treatment hold?), with the home indicator (does the bottom CTA clear it?), and in landscape if supported.
Navigation titles belong to the navigator. Use the stack's native title (and large-title collapse behavior on iOS) rather than a hand-rolled header whenever possible.
Haptics are punctuation. Light impact on selection/confirm on iOS, success/warning notifications for outcomes. Never on scroll, never in loops. Guard with platform checks.
Format numbers like a product, not a database: 1.4M, 38k, $4.99. Trim trailing zeros. Localize dates.
Root scroll behavior: screens that can ever overflow wrap content in a ScrollView (first component in the route) with
```
contentInsetAdjustmentBehavior="automatic"
```
. Use
```
useWindowDimensions
```
, never
```
Dimensions.get()
```
.

这些细节是区分“套壳网页”与“原生应用”的关键。违反任何一条都属于问题，而非风格偏好。

从第一天起就支持语义化色彩与双主题。使用系统/语义化颜色令牌（例如iOS端
```
expo-router
```
中的
```
Color
```
：
```
Color.ios.label
```
、
```
Color.ios.secondarySystemBackground
```
；Android端使用Material动态色彩）。每个界面在“完成”前必须在浅色和深色模式下都能正确渲染。绝不要将语义化颜色对象传入Reanimated的动画样式中——需先解析为字符串。
优先使用原生控件而非自定义重构控件。开关、滑块、分段控件、上下文菜单、日期选择器：使用原生控件或忠实的封装组件。一个动画效果与iOS原生控件相差50毫秒的自定义切换控件会立刻显得虚假。
图标使用SF Symbols / Material Symbols。iOS端优先使用SF Symbols（通过
```
expo-image
```
的
```
sf:
```
源，或
```
expo-symbols
```
）；它们会继承字重、光学尺寸和动态字体行为。同一界面不要混用三种以上的图标库。
排版即层级。使用平台的字体层级（iOS端的大标题/标题/标题文本/正文/脚注）。每个界面仅使用一种展示字号。任何计数、时间或价格内容使用等宽数字（
```
fontVariant: ['tabular-nums']
```
）。用户可能需要复制的数据需设置
```
Text selectable
```
。
连续圆角。所有圆角矩形都设置
```
borderCurve: 'continuous'
```
。圆角矩形是让应用“看起来像iOS应用”的最便捷优化手段。
通过CSS
boxShadow
实现阴影，而非旧版的
```
shadow*
```
/
```
elevation
```
属性。阴影用于体现层级逻辑，而非装饰——整个应用使用统一的层级系统。
间距节奏。选择一个基础单位（4或8）并严格遵循。优先使用flexbox的
```
gap
```
而非margin堆叠。ScrollView的内边距需设置在
```
contentContainerStyle
```
中，绝不要直接设置在ScrollView本身。
安全区域与灵动岛是设计的一部分。必须验证界面内容在灵动岛/状态栏下方滚动时的效果（模糊/渐变处理是否有效？）、底部CTA是否避开Home指示器、以及支持横屏时的横屏显示效果。
导航标题属于导航器。尽可能使用栈导航的原生标题（以及iOS端的大标题折叠效果），而非手动实现的头部组件。
触觉反馈是“标点符号”。iOS端选择/确认时使用轻量震动，结果通知使用成功/警告震动。绝不要在滚动时或循环中使用触觉反馈。需通过平台检查进行适配。
像产品一样格式化数字，而非像数据库：1.4M、38k、$4.99。去除末尾的零。日期需本地化。
根滚动行为：任何可能溢出的界面需将内容包裹在ScrollView中（作为路由的第一个组件），并设置
```
contentInsetAdjustmentBehavior="automatic"
```
。使用
```
useWindowDimensions
```
，绝不要使用
```
Dimensions.get()
```
。

Motion laws

动效准则

Motion is the highest-leverage polish surface and the easiest to overdo.

Every animation needs a reason: continuity (element moves between states), causality (response to a gesture), or orientation (where did this come from). Decoration-only motion gets cut.
Reanimated worklets on the UI thread for anything tracking a gesture. Gesture → animation must never hop the JS thread.
Springs over durations for anything the user "touches"; gentle timing curves (250–350 ms, ease-out) for anything the system initiates.
Entering/exiting animations (
```
FadeIn
```
,
```
SlideInDown
```
, layout transitions) on list items, modals, and conditional content — subtle, 150–250 ms.
Respect Reduce Motion. Query the accessibility setting and collapse spatial animations to cross-fades.
The bar to hit: 60 fps on a mid-tier device, zero dropped frames during the hero transition of your flow. Measure, don't vibe — see references/performance.md.

动效是提升质感的最高效手段，但也最容易过度使用。

每个动画都要有理由：连续性（元素在状态间移动）、因果性（响应用户手势）或导向性（说明元素来源）。仅用于装饰的动效应删除。
跟踪手势的动画需在UI线程使用Reanimated worklets。手势→动画的流程绝不要跨越JS线程。
用户“触摸”的元素使用弹簧动画而非固定时长；系统触发的动画使用平缓的时间曲线（250–350毫秒，缓出）。
列表项、模态框和条件内容使用进入/退出动画（
```
FadeIn
```
、
```
SlideInDown
```
、布局过渡）——效果要柔和，时长150–250毫秒。
尊重“减少动效”设置。查询辅助功能设置，将空间动画简化为淡入淡出。
达标要求：中端设备上达到60fps，流程中的核心过渡无丢帧。要测量，不要凭感觉——参考references/performance.md。

State architecture

状态架构

Screens that feel great are screens whose state is boring:

Server state in TanStack Query (or the project's equivalent): caching, retries, optimistic updates. Never
```
useEffect
```
+
```
fetch
```
.
Client state in a small atomic store (Zustand/Jotai). Broad "app state" contexts cause the re-render cascades that make UIs feel heavy.
Ephemeral UI state (open/closed, focus, scroll) stays local to the component.
Optimistic by default: taps reflect instantly, reconcile in the background, roll back loudly on failure.
Uncontrolled
```
TextInput
```
s for high-frequency typing surfaces; controlled inputs are a top-3 cause of typing jank.
Persist tiny client state in MMKV, not AsyncStorage, when latency shows.

质感出色的界面，其状态管理往往简洁明了：

服务端状态使用TanStack Query（或项目的等效工具）：缓存、重试、乐观更新。绝不要使用
```
useEffect
```
+
```
fetch
```
。
客户端状态使用小型原子状态库（Zustand/Jotai）。宽泛的“应用状态”上下文会导致重渲染连锁反应，让UI显得卡顿。
临时UI状态（展开/收起、焦点、滚动）保留在组件本地。
默认启用乐观更新：点击操作立即反馈，后台进行数据同步，失败时显著回滚。
高频输入场景使用非受控
```
TextInput
```
；受控输入是导致输入卡顿的三大原因之一。
当存在延迟问题时，将小型客户端状态持久化到MMKV，而非AsyncStorage。

Perceived performance

感知性能

Skeletons only for content whose shape you know; otherwise progressive reveal. Never a full-screen spinner for a partial update.
FlashList for every list; give stable keys.
Preload the next screen's data on press-in, not on navigation-complete.
Images: right-size sources,
```
expo-image
```
with
```
recyclingKey
```
in lists, thumbhash/blurhash placeholders.
Cold-start TTI and bundle discipline live in references/performance.md — apply the measure → optimize → re-measure loop, never blind memoization.

仅对已知形状的内容使用骨架屏；否则使用渐进式加载。局部更新时绝不要使用全屏加载 spinner。
所有列表都使用FlashList；提供稳定的key。
在用户按下按钮时预加载下一个界面的数据，而非在导航完成后。
图片：使用合适尺寸的源，列表中使用带
```
recyclingKey
```
的
```
expo-image
```
，使用thumbhash/blurhash占位符。
冷启动TTI和包体积优化请参考references/performance.md——遵循“测量→优化→重新测量”的循环，绝不要盲目使用memoization。

Image & illustration assets

图片与插画资源

When a screen calls for illustration, empty-state art, hero imagery, or icons beyond the symbol set:

Generate assets with the best image model available to you (e.g. an imagegen tool or the Higgsfield MCP/CLI if connected) at the highest quality settings, then downscale to @1x/@2x/@3x. Never upscale.
One visual language per app: pick a style (gradient-mesh, flat-duotone, 3D-clay, hand-drawn, mascot style) and generate ALL assets in that same style, same palette, same lighting. A mixed-style asset set reads as template slop.
Prompt for transparent or solid-flat backgrounds matched to your surface color; composite artifacts (white halos, wrong-color mattes) are an automatic redo.
Full asset pipeline and prompt patterns: references/image-assets.md.

当界面需要插画、空状态图、主视觉图或符号库之外的图标时：

使用可用的最佳图像生成模型（例如图像生成工具，或已连接的Higgsfield MCP/CLI），以最高质量设置生成资源，然后缩小到@1x/@2x/@3x。绝不要放大资源。
整个应用使用统一的视觉风格：选择一种风格（渐变网格、扁平双色调、3D黏土风、手绘风、吉祥物风格），所有资源都使用相同风格、相同调色板、相同光影。混合风格的资源会显得像模板拼凑的产物。
生成时要求透明背景或与界面颜色匹配的纯色背景；合成瑕疵（白色光晕、错误颜色的遮罩）需重新生成。
完整的资源流程和提示模板请参考：references/image-assets.md。

The simulator loop (non-negotiable)

模拟器循环（不可协商）

A screen does not exist until you have seen it running. The loop:

Implement → launch in the iOS Simulator (or Android emulator).
Screenshot and actually look: alignment, optical centering, spacing rhythm, truncation with long content, dark mode, Dynamic Type at XL.
Exercise the motion: record, scrub frame by frame if a transition looks off. Watch content pass under the Dynamic Island and behind the tab bar.
Fix, relaunch, re-verify. Repeat until you cannot find a defect — then run the checklist in references/simulator-loop.md once more.

Do not declare a screen finished from code review alone. Do not stop at "looks fine" — stop at "cannot find a flaw at 100% zoom".

界面在你看到它运行之前都不算存在。循环流程：

实现→在iOS模拟器（或Android模拟器）中启动。
截图并仔细检查：对齐方式、视觉居中、间距节奏、长内容截断、深色模式、XL级动态字体。
测试动效：录制视频，若过渡效果异常则逐帧查看。观察内容在灵动岛下方和标签栏后方的显示效果。
修复、重启、重新验证。重复直到找不到缺陷——然后再运行一次references/simulator-loop.md中的检查清单。

不要仅通过代码评审就宣布界面完成。不要停留在“看起来不错”——要做到“放大到100%也找不到任何缺陷”。

Definition of done, per screen

单界面完成标准

References

参考资料

File	Load when
references/native-controls.md	Choosing/wiring iOS+Android native controls, menus, pickers, sheets
references/motion.md	Any Reanimated work: gestures, transitions, springs, layout animations
references/performance.md	Jank, slow TTI, big bundles, memory leaks, profiling method
references/image-assets.md	Generating illustrations/icons/hero art with image models
references/simulator-loop.md	Final verification checklist + device matrix

文件	适用场景
references/native-controls.md	选择/配置iOS+Android原生控件、菜单、选择器、底部弹窗
references/motion.md	任何Reanimated相关工作：手势、过渡、弹簧动画、布局动画
references/performance.md	卡顿、TTI缓慢、包体积过大、内存泄漏、性能分析方法
references/image-assets.md	使用图像模型生成插画/图标/主视觉图
references/simulator-loop.md	最终验证检查清单 + 设备矩阵