skills/appllama-usage/references/improve-a-screen.md

# Playbook: make an existing screen better

The user has a screen (code, screenshot, or a live app) and wants it better.
"Better" means: measurably closer to the best equivalent screens shipped by
top-grossing apps — in hierarchy, motion, and feel — verified in the
simulator, not eyeballed in code.

## 1. Diagnose before you search

Run the screen in the simulator and study it against appllama-app-design-skill's
definition-of-done checklist. Name the top 3 deficits precisely ("no visual
hierarchy — three same-weight text rows", "dead motion — modal pops with no
transition", "non-native segmented control"). The research pass is aimed at
these deficits, not at "inspiration".

## 2. The 30 + 30 reference board

Two searches, three pages each (10 per page) — and keep paging past three
if the results are still strong:

- `search_screens(query="<screen type / content words>", mode="keyword")` —
  finds screens NAMED like yours (e.g. "workout summary", "streak stats").
  Add filters that sharpen it: `screen_type`, `flow`, `element`.
- `search_screens(query="<what it should feel like>", mode="semantic")` —
  finds screens that LOOK like the goal ("calm dark stats dashboard with a
  hero number and weekly bars"). Different screens will surface — that's the
  point of running both.

Save all ~60 into a local board (see SKILL.md's structure). Pick the **best
5–8** and say why each earns its place. If one is nearly perfect, pull
`get_screen` on it — its `similar_screens` often surfaces an even better
sibling from another app.

## 3. Extract the pattern

From the picks, write the target: layout skeleton, hierarchy order, control
choices, spacing rhythm, palette role-mapping, motion moments (entrance,
press feedback, data reveal). This is a spec, not a mood board — every line
should be checkable in a screenshot.

## 4. Rebuild and iterate (the loop)

1. Implement against the spec using **appllama-app-design-skill** (typography
   ramp, semantic colors both themes, native controls, Reanimated motion
   with the platform's curves, state kept boring).
2. Asset gaps (illustration, empty-state art, icons beyond the symbol set):
   generate with the best available image model at max quality, one style
   system, per the design skill's image-assets reference.
3. **Simulator loop until perfect**: screenshot → compare side-by-side with
   your top references → fix → repeat. Record the motion and scrub it
   frame by frame. Verify Dynamic Island/safe areas, dark + light, Dynamic
   Type XL, Reduce Motion, 60fps on the interaction.
4. Do not stop at "better than before". Stop when the honest side-by-side
   with the best reference reads **at least as good** — hierarchy, motion,
   font discipline, state handling, everything. If it doesn't, name the gap
   and go around again.

## 5. If the screen is part of a flow

Screens live in journeys. After the screen passes, walk one step before and
one step after it in the simulator: entrance transition, exit transition,
state carried across — and what back does from it on iOS and Android
(appllama-app-design-skill's Navigation laws).
If the screen is a sheet, a modal or a step behind a one-way door, verify
its presentation matches what it *is*, not just how it looks. Use `get_flow_apps` + `list_app_screens(flow=…)` if
you need to see how winners chain the surrounding steps
(references/research-methods.md).