> ## 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 your app with a design system

> From reference screenshots to a design system.

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:

| File                 | What it holds                                          |
| -------------------- | ------------------------------------------------------ |
| `design-system.md`   | Design intent, rules, component specs                  |
| `DesignTokens.swift` | The only place visual values live                      |
| `AGENTS.md`          | The rules and flow you want any coding agent to follow |

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.

<Note>
  The example throughout: a co-parenting app with 4 screens — Home, Calendar, To-Do, Journal. Substitute your own screens.
</Note>

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

<Steps>
  <Step title="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.)
  </Step>

  <Step title="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.
  </Step>

  <Step title="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."
  </Step>

  <Step title="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.
  </Step>

  <Step title="Anti-references">
    1–2 things it must never look like: "no pastel baby-app vibes."
  </Step>
</Steps>

## Stage 1 — Direction (\~15 minutes)

Send your references with a message like:

```text theme={null}
Here are my style references. [images]
Ref 1: I like the monochrome grayscale, gradient depth, accent colors used only for meaning.
Anti: nothing neon, no default AI look.
My app: co-parenting app, 4 screens (content below). Feel: calm, trustworthy, grown-up.
First describe each reference back — what you see and what you'll take from it. Don't generate anything yet.
```

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.

<Tip>
  **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.
</Tip>

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.

<Warning>
  **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.
</Warning>

```text theme={null}
Build my Calendar screen in this direction as an iOS HTML mockup, light and dark.
Content: month grid; each day belongs to me or co-parent (that's the most important info); today marked; selected day shows its events below; add-event; bottom tabs: Home, Calendar, To-Do, Journal.
Commit to the direction — go bolder than safe, I'll pull back.
```

Each round, give **reactions, not specs**. Pick from the dial vocabulary:

<AccordionGroup>
  <Accordion title="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"
  </Accordion>
</AccordionGroup>

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:

```text theme={null}
Now my Home screen. Layout reference attached — take ONLY the structure: [image]
"layout only: the chronological timeline with the inline week strip; I also want an up-next hero like my current app (screenshot attached)."
First describe the layout back as zones/hierarchy — no colors, no fonts. Don't generate yet.
```

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.**

<Steps>
  <Step title="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**.
  </Step>

  <Step title="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
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.**
  </Step>
</Steps>

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

| Stage | You must give                                                             | You never give                      |
| ----- | ------------------------------------------------------------------------- | ----------------------------------- |
| 0     | agent rules, refs + captions, content of your screens, anti-refs          | exact hexes, spacing/radius numbers |
| 1     | corrections to describe-back, palette gut-check                           | exact values                        |
| 2     | screen content, dial reactions                                            | pixel values (unless you want to)   |
| 3     | layout ref + element caption, structure tweaks                            | style feedback (system handles it)  |
| 4     | 10-min read of the doc, token-file choice                                 | anything else                       |
| 5     | inputs (design-system files, HTML, north-star PNGs), screenshot reactions | code review                         |
| 6     | content of each new screen                                                | style words, code                   |