Skip to main content
You provide references that point at what you like — the shadows, background colors, fonts, spacing, corner radii — plus anything else that matters to you. From those, the agent derives the actual values and shows them for your approval. It usually takes a few iterations to get right. The workflow produces three files that keep every future screen consistent: Once these exist, every new screen comes out in the style you want — you’ll still make some edits, just far fewer and smaller than starting from scratch each time.
The example throughout: a co-parenting app with 4 screens — Home, Calendar, To-Do, Journal. Substitute your own screens.

​
Stage 0 — Prepare (what to have ready for each stage)

1

Set up the agent rules

Write the rules for the agent — the flow you want it to follow, whether the flow described here or your own enhanced version. Include a guardrail so it never builds from an unfinished system: tell the agent to treat any file whose STATUS says TEMPLATE as empty — never reading, copying, or building from it — and to keep every unfilled value as bright magenta so a not-yet-filled system can’t be mistaken for a design. (The design-system.md and DesignTokens.swift files themselves are created and filled at Stage 4 — keep them out of the project until then.)
2

Style reference (max 3)

Screenshots of the app whose visual language you want, plus a line on what you like about it — for example the shadows, the colors, the typography, the corner radius, the spacing and whitespace, the depth or gradients, the icon style, and the overall feel or mood. Can’t verbalize it? Write “not sure what I like — help me name it” and the agent proposes captions for you to confirm.
3

Layout references per screen (only if needed)

You only need these when you’re not happy with how the information is arranged — data in cards vs. rows, a calendar laid out a certain way, a summary section at the top. Either describe the arrangement you want in words, or grab a reference that shows it and point the agent at the specific element — “layout only: lay my tasks out as cards like this, not a list.”
4

Content list for each screen

Plain words describing what each screen shows. Example for Home: “greeting, next event with countdown, this-week custody strip, tomorrow’s events.” Or if you have a screenshot of your current app, that works perfectly.
5

Anti-references

1–2 things it must never look like: “no pastel baby-app vibes.”

​
Stage 1 — Direction (~15 minutes)

Send your references with a message like:
The agent describes each image back — correct anything misread before it contaminates the direction. Then it returns the direction: exact palette (light + dark), font proposal, radii, depth policy, and 2–3 signature elements.
Fonts. Either you know one (“we use Nunito” — it’s locked), or you say: “Propose 2–3 fonts that match the reference’s feel, must be free to bundle in an iOS app, and show me the same screen title in each.” You pick by looking, not by name.
Check whether it’s what you wanted — if not, keep iterating; if yes, move to the next stage.

​
Stage 2 — First north-star screen (2–4 rounds)

Start with the screen that carries your app’s core meaning — in the example, Calendar (it carries the custody information). This first screen is your north-star: the exemplar every later screen follows, so it absorbs all the taste decisions. Give the agent a screenshot of this screen from your current app (if you have one) plus its content, and ask it to build it in the direction you chose. Then check: did it apply that direction, and does it work for you? When something’s off, you have three moves: describe the fix in words (the dial vocabulary below), point the agent at a reference that shows what you want, or ask it to research how similar tools handle the screen and show you a few options to pick from. Keep style and layout separate — if the look is right but the calendar’s arrangement isn’t, that’s a layout reference, not a style change.
Common pitfall — the agent styles from an empty template. If the design-system.md and DesignTokens.swift templates sit in your project before they’re filled, the agent may read their placeholder values and build from them — so your screens come out looking like the blank template, not your design. This is exactly what the Stage 0 guardrail prevents (mark unfilled files TEMPLATE, keep values magenta) — and why you keep them out of the project until Stage 4.
Each round, give reactions, not specs. Pick from the dial vocabulary:
  • color: warmer / cooler / more muted / “bg must be white”
  • weight: lighter / heavier, thinner / thicker
  • space: denser / airier
  • shape: rounder / sharper, “like the reference” (the agent re-checks the image)
  • depth: flatter / more depth, gradient vs shadow
  • type: quieter / louder, bigger / smaller
  • and mark what’s RIGHT: “tiles perfect, don’t touch”
Exit when you’d ship it: “approved, north-star 1.”

​
Stage 3 — Second north-star, with a layout reference (2–3 rounds)

Do the second screen the same way as the first — same build-check-fix loop — but pick one that’s structurally different (here, Home: hero card, lists, text) so you prove the style holds beyond a single layout. This time, lead with a layout reference:
Iterate on the structure — what’s visible without scrolling, denser/airier, card vs plain list, section order. You can tweak the style here too, but don’t fix it on this one screen: tell the agent to change it in the system so every screen inherits the change. And reuse components across screens — if the same element shows up in more than one place (say the week-day strip on Home and the day tiles on Calendar), it should be one shared component, not two look-alikes, so spacing, font sizes, and behavior stay identical everywhere. Exit: “approved, north-star 2. Lock it.”

​
Stage 4 — Freeze (one command)

When you’re happy with the style and ready to lock it, ask the agent to populate the design files with every decision from Stages 1–3:
  • design-system.md — the intent, rules, and component specs
  • DesignTokens.swift — the values, your single source of truth
Two ways to set up the token file: take Modaal’s Swift token files and edit them with your values, or ask the agent to create them from scratch. Either way, DesignTokens.swift becomes the one place your visual values live. The agent also saves the north-star screenshots. Then review: read design-system.md §1–2 (about 10 minutes) — check that the words describe your app’s feel and the signature elements are the ones you approved, then commit the files.

​
Stage 5 — Into the app (redesign in Modaal)

When the design side is done, you hand your work to Modaal — step by step. Two passes: swap the tokens first, then rebuild screen by screen.
1

Open Modaal in plan mode and let it scope the work

Open Modaal in plan mode, ask it to redesign, and have it propose the most efficient approach first — before it touches anything. Bring three inputs: the design-system files, the HTML mockups, and the north-star PNGs.
2

Swap the tokens first — gradually, one group at a time

Ask Modaal to replace the app’s existing tokens with your new ones, one group per pass rather than all at once:
  1. color — primary · secondary · accent
  2. radius
  3. spacing
  4. typography — families · sizes · weights
3

Then go screen by screen

With the tokens in, iterate one screen at a time:
  • Claude writes the spec + HTML + PNG
  • → Modaal builds the screen
  • → stuck? Claude re-describes that piece
  • → layout, grids & page structure back to Modaal
Layout goes over as words, never as code.
4

Let Claude write the Modaal prompt

You don’t phrase the handoff yourself — have Claude write the Modaal prompt for you, then iterate until you’re happy. Every future visual change comes back as screenshots for review, never code.
Expect one small adjustment pass on the first native render — fonts and curves come out slightly differently than in the HTML, usually better.

​
Stage 6 — New screens, straight in Modaal

Once your screens are in Modaal, you can create new ones directly there — they’re built in your style automatically, and you can edit them right in Modaal.

​
Keeping it consistent over time

The system gives you consistency, but agents still drift — a hardcoded color here, a one-off component there. Every so often (say, every ~10 screens), ask the agent to audit: scan for hardcoded values that should be tokens, check text contrast in both light and dark mode, and confirm repeated elements still use the same shared component. Fix any drift by updating the token or the component, not the individual screens.

​
Summary — what you give at each stage