> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modaal.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Design prompts that work
> The vocabulary and copy-paste prompts for polishing your app's design — spacing, contrast, tap targets, consistency, motion, and the full audit.
Once your design system exists, most design work is a short prompt away. This page gives you the vocabulary to describe what you see, plus copy-paste prompts for the checks non-designers most often miss.
## The vocabulary
* *"more breathing room / airier"* → bigger gaps
* *"tighter / denser"* → smaller gaps
* *"the padding inside the card"* → space between a card's edge and its contents
* *"the margin"* → space from the screen edge to the content
* *"the gap / the rhythm between items"* → space between repeated elements
Useful sentence: *"Increase the vertical rhythm between sections by one step on the spacing scale."*
iOS uses a fixed type scale. You rarely need the numbers, but here they are so you can point at a role:
* **34pt** — large title (the big screen title)
* **22pt** — title
* **17pt** — body / headline (default reading size; anything smaller starts to look like a website)
* **15pt** — subheadline
* **13pt / 11pt** — caption / metadata (timestamps, labels)
The words iOS uses, light to heavy: **regular → medium → semibold → bold**. *"Make the amount semibold so it stands out from the label."*
* **accent / primary** — the interactive color (buttons, active tab, selection)
* **surface / background** — the color behind content (card vs screen)
* **ink / text-primary / text-secondary** — text colors: primary for headings, secondary for supporting text
* **semantic roles** — success, warning, error, plus your app's own named roles
* **corner radius** — how rounded corners are (*"softer corners"* / *"sharper corners"*)
* **elevation / shadow / depth policy** — whether things float on shadows, sit on surfaces, or use gradients. Your system should pick *one* policy; point at it: *"we use surfaces, not shadows — remove that drop shadow."*
* **tap target** — the invisible touchable area (must be at least **44×44pt**)
* **pressed / disabled state** — how something looks when tapped or unavailable
* **hairline** — a 1px divider line
Not sure what to ask for? Use this:
```text theme={null}
I don't love this screen but can't name why. Give me 4 dials I can react to — like warmer/cooler, airier/denser, quieter/louder type, softer/sharper shapes — and show me what pushing each one would do.
```
## Reuse values and components
Extract repeated things into shared components:
```text theme={null}
Look across all my screens. Find any visual element that repeats — cards, buttons, list rows, headers, badges. For each, tell me if it's built the same way everywhere or if there are subtle differences. Then propose turning the repeated ones into a single shared component that every screen uses.
```
Before building anything new, reuse what exists:
```text theme={null}
I want to add a [new screen / new element]. Build it from the existing components and tokens so it matches the rest of the app. Only if nothing existing fits, add the new piece to the design system rather than to just this screen.
```
## Accessibility — text contrast
```text theme={null}
Run an accessibility contrast check on this screen. Check every text element against its background, in both light and dark mode, and tell me whether each one passes WCAG AA. Flag anything that fails and suggest the smallest fix.
```
For dots, icons, and other non-text elements:
```text theme={null}
Also check non-text elements that carry meaning — status dots, icons, selection outlines, dividers. Flag any that don't have enough contrast against their background, and suggest a fix.
```
## Tap targets
Anything tappable must be at least **44×44pt**, even if the visible icon is smaller.
```text theme={null}
Check every interactive element — buttons, chevrons, icons, toggles, list rows, close buttons. Measure each one's tap target. Flag anything smaller than 44×44pt and fix it by adding padding around the element (grow the touchable area, don't necessarily grow the visible icon). Confirm the fix doesn't push neighboring elements out of alignment.
```
Quick version for a single element: *"Is this chevron's tap target at least 44pt? If not, pad it to 44 without moving the icon."*
## Consistency check
The catch-all "does this all feel like one app" review:
```text theme={null}
Do a consistency pass across all my screens. For each recurring element, and for spacing rhythm, corner radii, font sizes and weights for equivalent roles, button styles, how headers are built, icon style and weight, and color usage by role — check whether every screen does it the same way. Give me a table of every inconsistency, ranked by how noticeable it is, and recommend which version should become the standard.
```
Follow-up once you've picked the standards:
```text theme={null}
For the inconsistencies we agreed on, make the fixes by updating tokens or shared components — not by editing screens one by one. Show me the list of tokens/components you changed.
```
## Check for hardcoded values
"Hardcoded" means a number or color typed directly into a screen instead of pulled from the token file. It's the #1 source of drift — it looks fine today and breaks consistency the moment you restyle.
```text theme={null}
Scan all my SwiftUI screens for hardcoded values — any color, font size, spacing number, or corner radius written literally instead of read from DesignTokens.swift — and fix them. Where there's a clear matching token, just swap it in. Where a value is close to an existing token, snap it to that token. Only pause for me on the genuine judgment calls: a value that doesn't map to anything and might need a new token. When you're done, give me a short summary of what you changed and the few decisions (if any) you want me to confirm.
```
Your `DesignTokens.swift` is the source of truth. A restyle should be a **one-file edit**. Every hardcoded value is a place that edit will silently miss.
## Animation and motion
Describe motion by **feel and purpose**; the agent picks the spring, duration, and easing. The vocabulary: *spring vs ease*, *snappy vs gentle*, *duration*, and *transition* (how something enters/exits).
Describing a motion you want — no jargon needed:
```text theme={null}
When a new event is added to the calendar, I want it to feel like it gently settles into place — not a hard pop. Use a spring that's soft, not bouncy, quick enough to not feel sluggish. Show me the values you chose and let me react.
```
Iterating on a motion that's not quite right:
```text theme={null}
This animation feels off. Give me dials to react to: faster/slower, bouncier/calmer, bigger/subtler movement, and where it starts from. Show me what each extreme looks like so I can pick.
```
Respect the accessibility setting:
```text theme={null}
Make sure every animation respects Reduce Motion — when it's on, replace movement with a simple fade or no animation. Check this is wired up everywhere, not just on the main screen.
```
## Things non-designers forget
**Dark mode** — half your users:
```text theme={null}
Verify every screen has proper dark-mode tokens. Flag anything that's just inverted or looks washed out rather than deliberately designed.
```
**Empty / loading / error states** — screens aren't always full of data:
```text theme={null}
For each screen, do I handle the empty state (no data yet), the loading state, and the error state? Show me which are missing and propose designs consistent with the system.
```
**Icon consistency:**
```text theme={null}
Verify all my icons come from one family (SF Symbols), share a weight that matches adjacent text, and none are a stray web/emoji icon.
```
## The big audit — everything at once
```text theme={null}
Do a full design-system audit of my iOS app. Use design-system.md and DesignTokens.swift as the source of truth. Cover, and give me a ranked findings table for each:
1. Hardcoded values — anything not read from the token file
2. Text contrast — WCAG AA, light and dark
3. Non-text contrast — dots, icons, dividers at 3:1
4. Tap targets — everything interactive ≥ 44×44pt
5. Cross-screen consistency — recurring elements that drift
6. Dark mode — deliberate, not just inverted
7. Reused components — repeated elements that should be shared
For each finding: the screen/file, what's wrong, severity, and the smallest fix (preferring a token or shared-component change over per-screen edits). Don't fix anything yet — show me the table first, and I'll tell you what to apply.
```