1---
2name: sleek-design-mobile-apps
3description: Use when the user wants to design a mobile app, create screens, build UI, or interact with their Sleek projects. Covers high-level requests ("design an app that does X") and specific ones ("list my projects", "create a new project", "screenshot that screen").
4compatibility: Requires SLEEK_API_KEY environment variable. Network access limited to https://sleek.design only.
5metadata:
6  requires-env: SLEEK_API_KEY
7  allowed-hosts: https://sleek.design
8---
9 
10# Designing with Sleek
11 
12[![Design mobile apps in minutes](https://raw.githubusercontent.com/sleekdotdesign/agent-skills/main/assets/hero.png)](https://sleek.design)
13 
14## Overview
15 
16[sleek.design](https://sleek.design) is an AI-powered mobile app design tool. You interact with it via a REST API at `/api/v1/*` to create projects, describe what you want built in plain language, and get back rendered screens. All communication is standard HTTP with bearer token auth.
17 
18**Base URL**: `https://sleek.design`
19**Auth**: `Authorization: Bearer $SLEEK_API_KEY` on every `/api/v1/*` request
20**Content-Type**: `application/json` (requests and responses)
21**CORS**: Enabled on all `/api/v1/*` endpoints
22 
23---
24 
25## Prerequisites: API Key
26 
27Create API keys at **https://sleek.design/dashboard/api-keys**. The full key value is shown only once at creation — store it in the `SLEEK_API_KEY` environment variable.
28 
29**Required plan**: Pro or higher (API access is gated)
30 
31### Key scopes
32 
33| Scope             | What it unlocks              |
34| ----------------- | ---------------------------- |
35| `projects:read`   | List / get projects          |
36| `projects:write`  | Create / delete projects     |
37| `components:read` | List components in a project |
38| `chats:read`      | Get chat run status          |
39| `chats:write`     | Send chat messages           |
40| `screenshots`     | Render component screenshots |
41 
42Create a key with only the scopes needed for the task.
43 
44---
45 
46## Security & Privacy
47 
48- **Single host**: All requests go exclusively to `https://sleek.design`. No data is sent to third parties.
49- **HTTPS only**: All communication uses HTTPS. The API key is transmitted only in the `Authorization` header to Sleek endpoints.
50- **Minimal scopes**: Create API keys with only the scopes required for the task. Prefer short-lived or revocable keys.
51- **Image URLs**: When using `imageUrls` in chat messages, those URLs are fetched by Sleek's servers. Avoid passing URLs that contain sensitive content.
52 
53---
54 
55## Quick Reference — All Endpoints
56 
57| Method   | Path                                    | Scope             | Description       |
58| -------- | --------------------------------------- | ----------------- | ----------------- |
59| `GET`    | `/api/v1/projects`                      | `projects:read`   | List projects     |
60| `POST`   | `/api/v1/projects`                      | `projects:write`  | Create project    |
61| `GET`    | `/api/v1/projects/:id`                  | `projects:read`   | Get project       |
62| `DELETE` | `/api/v1/projects/:id`                  | `projects:write`  | Delete project    |
63| `GET`    | `/api/v1/projects/:id/components`       | `components:read` | List components   |
64| `GET`    | `/api/v1/projects/:id/components/:componentId` | `components:read` | Get component |
65| `POST`   | `/api/v1/projects/:id/chat/messages`    | `chats:write`     | Send chat message |
66| `GET`    | `/api/v1/projects/:id/chat/runs/:runId` | `chats:read`      | Poll run status   |
67| `POST`   | `/api/v1/screenshots`                   | `screenshots`     | Render screenshot |
68 
69All IDs are stable string identifiers.
70 
71---
72 
73## Endpoints
74 
75### Projects
76 
77#### List projects
78 
79```http
80GET /api/v1/projects?limit=50&offset=0
81Authorization: Bearer $SLEEK_API_KEY
82```
83 
84Response `200`:
85 
86```json
87{
88  "data": [
89    {
90      "id": "proj_abc",
91      "name": "My App",
92      "slug": "my-app",
93      "createdAt": "2026-01-01T00:00:00Z",
94      "updatedAt": "..."
95    }
96  ],
97  "pagination": { "total": 12, "limit": 50, "offset": 0 }
98}
99```
100 
101#### Create project
102 
103```http
104POST /api/v1/projects
105Authorization: Bearer $SLEEK_API_KEY
106Content-Type: application/json
107 
108{ "name": "My New App" }
109```
110 
111Response `201` — same shape as a single project.
112 
113#### Get / Delete project
114 
115```http
116GET    /api/v1/projects/:projectId
117DELETE /api/v1/projects/:projectId   → 204 No Content
118```
119 
120---
121 
122### Components
123 
124#### List components
125 
126```http
127GET /api/v1/projects/:projectId/components?limit=50&offset=0
128Authorization: Bearer $SLEEK_API_KEY
129```
130 
131Response `200`:
132 
133```json
134{
135  "data": [
136    {
137      "id": "cmp_xyz",
138      "name": "Hero Section",
139      "activeVersion": 3,
140      "versions": [{ "id": "ver_001", "version": 1, "code": "<!DOCTYPE html>...</html>", "createdAt": "..." }],
141      "createdAt": "...",
142      "updatedAt": "..."
143    }
144  ],
145  "pagination": { "total": 5, "limit": 50, "offset": 0 }
146}
147```
148 
149#### Get component
150 
151Fetches a single component by ID. Use this when you need the code for a specific screen (e.g., after a chat run returns a `componentId` in its operations).
152 
153```http
154GET /api/v1/projects/:projectId/components/:componentId
155Authorization: Bearer $SLEEK_API_KEY
156```
157 
158Response `200` — same shape as a single item from the list endpoint:
159 
160```json
161{
162  "data": {
163    "id": "cmp_xyz",
164    "name": "Hero Section",
165    "activeVersion": 3,
166    "versions": [{ "id": "ver_001", "version": 1, "code": "<!DOCTYPE html>...</html>", "createdAt": "..." }],
167    "createdAt": "...",
168    "updatedAt": "..."
169  }
170}
171```
172 
173---
174 
175### Chat — Send Message
176 
177This is the core action: describe what you want in `message.text` and the AI creates or modifies screens.
178 
179```http
180POST /api/v1/projects/:projectId/chat/messages?wait=false
181Authorization: Bearer $SLEEK_API_KEY
182Content-Type: application/json
183idempotency-key: <optional, max 255 chars>
184 
185{
186  "message": { "text": "Add a pricing section with three tiers" },
187  "imageUrls": ["https://example.com/ref.png"],
188  "target": { "screenId": "scr_abc" }
189}
190```
191 
192| Field                    | Required | Notes                                         |
193| ------------------------ | -------- | --------------------------------------------- |
194| `message.text`           | Yes      | 1+ chars, trimmed                             |
195| `imageUrls`              | No       | HTTPS URLs only; included as visual context   |
196| `target.screenId`        | No       | Edit a specific screen using its `screenId` (not `componentId`); omit to let AI decide |
197| `?wait=true/false`       | No       | Sync wait mode (default: false)               |
198| `idempotency-key` header | No       | Replay-safe re-sends                          |
199 
200#### Response — async (default, `wait=false`)
201 
202Status `202 Accepted`. `result` and `error` are absent until the run reaches a terminal state.
203 
204```json
205{
206  "data": {
207    "runId": "run_111",
208    "status": "queued",
209    "statusUrl": "/api/v1/projects/proj_abc/chat/runs/run_111"
210  }
211}
212```
213 
214#### Response — sync (`wait=true`)
215 
216Blocks up to **300 seconds**. Returns `200` when completed, `202` if timed out.
217 
218```json
219{
220  "data": {
221    "runId": "run_111",
222    "status": "completed",
223    "statusUrl": "...",
224    "result": {
225      "assistantText": "I added a pricing section with...",
226      "operations": [
227        { "type": "screen_created", "screenId": "scr_xyz", "screenName": "Pricing", "componentId": "cmp_xyz" },
228        { "type": "screen_updated", "screenId": "scr_abc", "componentId": "cmp_abc" },
229        { "type": "theme_updated" }
230      ]
231    }
232  }
233}
234```
235 
236---
237 
238### Chat — Poll Run Status
239 
240Use this after async send to check progress.
241 
242```http
243GET /api/v1/projects/:projectId/chat/runs/:runId
244Authorization: Bearer $SLEEK_API_KEY
245```
246 
247Response — same shape as send message `data` object:
248 
249```json
250{
251  "data": {
252    "runId": "run_111",
253    "status": "queued",
254    "statusUrl": "..."
255  }
256}
257```
258 
259When completed successfully, `result` is present:
260 
261```json
262{
263  "data": {
264    "runId": "run_111",
265    "status": "completed",
266    "statusUrl": "...",
267    "result": {
268      "assistantText": "...",
269      "operations": [...]
270    }
271  }
272}
273```
274 
275When failed, `error` is present:
276 
277```json
278{
279  "data": {
280    "runId": "run_111",
281    "status": "failed",
282    "statusUrl": "...",
283    "error": { "code": "execution_failed", "message": "..." }
284  }
285}
286```
287 
288**Run status lifecycle**: `queued` → `running` → `completed | failed`
289 
290---
291 
292### Screenshots
293 
294Takes a snapshot of one or more rendered components.
295 
296```http
297POST /api/v1/screenshots
298Authorization: Bearer $SLEEK_API_KEY
299Content-Type: application/json
300 
301{
302  "componentIds": ["cmp_xyz", "cmp_abc"],
303  "projectId": "proj_abc",
304  "format": "png",
305  "scale": 2,
306  "gap": 40,
307  "padding": 40,
308  "background": "transparent"
309}
310```
311 
312| Field        | Default       | Notes                                                                 |
313| ------------ | ------------- | --------------------------------------------------------------------- |
314| `format`     | `png`         | `png` or `webp`                                                      |
315| `scale`      | `2`           | 1–3 (device pixel ratio)                                             |
316| `gap`        | `40`          | Pixels between components                                            |
317| `padding`       | `40`          | Uniform padding on all sides                                         |
318| `paddingX`      | _(optional)_  | Horizontal padding; overrides `padding` for left/right when provided |
319| `paddingY`      | _(optional)_  | Vertical padding; overrides `padding` for top/bottom when provided   |
320| `paddingTop`    | _(optional)_  | Top padding; overrides `paddingY` when provided                      |
321| `paddingRight`  | _(optional)_  | Right padding; overrides `paddingX` when provided                    |
322| `paddingBottom` | _(optional)_  | Bottom padding; overrides `paddingY` when provided                   |
323| `paddingLeft`   | _(optional)_  | Left padding; overrides `paddingX` when provided                     |
324| `background`    | `transparent` | Any CSS color (hex, named, `transparent`)                            |
325| `showDots`      | `false`       | Overlay a subtle dot grid on the background                          |
326| `radius`        | `48`          | Squircle corner radius per component in pixels (integer ≥ 0); pass `0` for sharp corners |
327 
328Padding resolves with a cascade: per-side → axis → uniform. For example, `paddingTop` falls back to `paddingY`, which falls back to `padding`. So `{ "padding": 20, "paddingX": 10, "paddingLeft": 5 }` gives top/bottom 20px, right 10px, left 5px.
329 
330When `showDots` is `true`, a dot pattern is drawn over the background color. The dots automatically adapt to the background: dark backgrounds get light dots, light backgrounds get dark dots. This has no effect when `background` is `"transparent"`.
331 
332Always use `"background": "transparent"` unless the user explicitly requests a specific background color.
333 
334Response: raw binary `image/png` or `image/webp` with `Content-Disposition: attachment`.
335 
336---
337 
338## Error Shapes
339 
340```json
341{ "code": "UNAUTHORIZED", "message": "..." }
342```
343 
344| HTTP | Code                    | When                                   |
345| ---- | ----------------------- | -------------------------------------- |
346| 401  | `UNAUTHORIZED`          | Missing/invalid/expired API key        |
347| 403  | `FORBIDDEN`             | Valid key, wrong scope or plan         |
348| 404  | `NOT_FOUND`             | Resource doesn't exist                 |
349| 400  | `BAD_REQUEST`           | Validation failure                     |
350| 409  | `CONFLICT`              | Another run is active for this project |
351| 500  | `INTERNAL_SERVER_ERROR` | Server error                           |
352 
353Chat run-level errors (inside `data.error`):
354 
355| Code               | Meaning                          |
356| ------------------ | -------------------------------- |
357| `out_of_credits`   | Organization has no credits left |
358| `execution_failed` | AI execution error               |
359 
360---
361 
362## Prompting Sleek
363 
364Sleek has its own AI that plans screen content, visual style, and layout. Pass the user's request to Sleek as-is — don't add details the user didn't ask for. If the user described specific screens and styling, include those. If they just said "build me a running app," send that and let Sleek decide the rest. Sleek produces richer designs when given room to plan, so avoid inventing screen content or layout details that the user didn't specify.
365 
366---
367 
368## Designing
369 
370### 1. Create a project
371 
372Create a project with `POST /api/v1/projects` if one doesn't exist yet. Ask the user for a name, or derive one from the request.
373 
374Each project has its own theme, style, and design system. If the user wants multiple design variations, create a separate project for each variation.
375 
376### 2. Send a chat message
377 
378Describe what to build using `POST /api/v1/projects/:id/chat/messages`. You can use the user's words directly — Sleek's AI interprets natural language. You do not need to decompose the request into screens; send the full intent as a single message and let Sleek decide what screens to create.
379 
380Chat messages are async by default — you get a `runId` and poll for completion with `GET /api/v1/projects/:id/chat/runs/:runId`. You can also use `?wait=true` for a blocking call (up to 300s; falls back to polling if it times out with `202`).
381 
382**Polling**: start at 2s interval, back off to 5s after 10s, give up after 5 minutes.
383 
384**Editing a specific screen**: use `target.screenId` to direct changes to the right screen (uses the screen ID from operations, not the component ID).
385 
386**One run at a time**: only one active run is allowed per project. If you get `409 CONFLICT`, wait for the current run to complete before sending the next message. Messages to different projects can run in parallel — use async polling (not `?wait=true`) when running multiple projects concurrently.
387 
388**Safe retries**: add an `idempotency-key` header (≤255 chars) to replay-safe re-sends. The server returns the existing run rather than creating a duplicate.
389 
390### 3. Show the results
391 
392After every chat run that produces `screen_created` or `screen_updated` operations, **always take screenshots and show them to the user** using `POST /api/v1/screenshots`. Never silently complete a chat run without delivering the visuals.
393 
394- **New screens**: one screenshot per screen + one combined screenshot of all screens in the project.
395- **Updated screens**: one screenshot per affected screen.
396 
397Use `background: "transparent"` for all screenshots unless the user explicitly requests otherwise.
398 
399Save screenshots in the project directory (not a temporary folder) so the user can easily view them.
400 
401---
402 
403## Implementing Designs
404 
405When the user wants to implement the designs in code (not just preview them), **always fetch the component HTML code** — do not rely on screenshots alone.
406 
407Use `GET /api/v1/projects/:id/components/:componentId` to fetch each screen's code. The `componentId` comes from the chat run's `result.operations`.
408 
409### HTML prototypes
410 
411The component `code` is a complete HTML document — save it directly to a `.html` file. No build step needed.
412 
413### Native frameworks (React Native, SwiftUI, etc.)
414 
415Use both the HTML code and the screenshots together:
416 
417- **HTML code** is the implementation reference — it contains the exact structure, layout, styling, colors, spacing, content, image URLs, and icon names.
418- **Screenshots** are the visual target — use them to verify your implementation matches the intended look.
419 
420The HTML tells you *how* to build it; the screenshot tells you *what* it should look like.
421 
422#### Icons
423 
424Sleek uses [Iconify](https://iconify.design) icons in the format `prefix:name` (e.g., `solar:heart-bold`, `material-symbols:search-rounded`, `lucide:settings`). The most common sets are **Solar**, **Hugeicons**, **Material Symbols** and **MDI**.
425 
426**Use the exact icons from the HTML code** — do not substitute with a different icon set. Matching icons is important for design fidelity.
427 
428When implementing icons:
429 
4301. **Check if the project already has an icon system** that supports the same sets Sleek uses (Solar, Hugeicons, Material Symbols, MDI). If so, use it. Note: `@expo/vector-icons` does **not** support these sets — do not use it as a substitute.
4312. **Otherwise, fetch the SVGs from the Iconify API and embed them in the code:**
432   ```
433   GET https://api.iconify.design/{prefix}/{name}.svg
434   ```
435   Example: `https://api.iconify.design/solar/heart-bold.svg`
436 
437   Collect all icon names from the HTML, fetch their SVGs, and save them as static assets or string constants in the codebase. For **React Native / Expo**, render them with `react-native-svg`'s `SvgXml` component — this works in Expo Go with no additional native dependencies.
438 
439#### Fonts
440 
441The HTML includes Google Fonts via `<link>` tags in the `<head>`. Use the same fonts and weights when implementing in a native framework — extract the font family names and weights from the `<link>` tags.
442 
443#### Navigation
444 
445The designs may include navigation elements like tab bars and headers. Update the project's navigation styling and structure to match the designs — don't just implement the screen content while leaving the default navigation untouched.
446 
447---
448 
449## Pagination
450 
451All list endpoints accept `limit` (1–100, default 50) and `offset` (≥0). The response always includes `pagination.total` so you can page through all results.
452 
453```http
454GET /api/v1/projects?limit=10&offset=20
455```
456 
457---
458 
459## Tips
460 
461### Saving component HTML to files
462 
463Component code can be large. When saving it to `.html` files, avoid writing the content through your text output — this is slow and wastes tokens. Instead, use shell commands to fetch the API response and write it directly to disk (e.g., pipe the response body into a file). This applies to both single and multiple components.
464 
465---
466 
467## Common Mistakes
468 
469| Mistake                                             | Fix                                                                             |
470| --------------------------------------------------- | ------------------------------------------------------------------------------- |
471| Sending to `/api/v1` without `Authorization` header | Add `Authorization: Bearer $SLEEK_API_KEY` to every request                              |
472| Using wrong scope                                   | Check key's scopes match the endpoint (e.g. `chats:write` for sending messages) |
473| Sending next message before run completes           | Poll until `completed`/`failed` before next send                                |
474| Using `wait=true` on long generations               | It blocks 300s max; have a fallback to polling for `202` response               |
475| HTTP URLs in `imageUrls`                            | Only HTTPS URLs are accepted                                                    |
476| Assuming `result` is present on `202`               | `result` is absent until status is `completed`                                  |
477| Using `screenId` as `componentIds` in screenshots   | `screenId` and `componentId` are different; always use `componentId` from operations for screenshots |
478