# The Clawify design file (`.clawify.json`) — format v1

An open, portable JSON format for social-post designs, made for AI authoring.
Any tool — especially AI chat tools — can write one; importing it into
[Clawify Studio](https://studio.clawify.dev) makes **every element editable**
(drag, retype, restyle) and exportable as pixel-exact Instagram PNGs. Exporting
a template produces the same format, so files round-trip and double as backups.

## Top level

```jsonc
{
  "clawify": 1,                      // required — format version gate
  "name": "My design",               // template name (≤80 chars)
  "size": { "w": 1080, "h": 1080 },  // canvas px; 1080×1080, 1080×1350, 1080×1920 typical
  "pages": [ { "bg": …, "elements": [ … ] } ],  // 1–20 pages (IG carousel)
  "assets": { "a1": { "dataUrl": "data:image/png;base64,…" } }  // optional, embedded images
}
```

Coordinates: origin top-left, px, canvas = `size`. Import is forgiving: unknown
fields are dropped, invalid values fall back to defaults, out-of-enum values are
coerced — an AI's sloppy output still imports.

## Page

```jsonc
{
  "bg": { "type": "color", "color": "#faf6ea" },
  // or an embedded image, cover-fit with % focal point:
  // { "type": "image", "asset": "a1", "x": 50, "y": 50 },
  "elements": [ … ]                  // ≤200; array order = z-order (last on top)
}
```

## Elements

Common fields: `type`, `x`, `y`, `rot` (deg, default 0), `opacity` (0.05–1, default 1).

### text
```jsonc
{ "type": "text", "x": 80, "y": 200, "w": 900,
  "text": "大標題",                   // height is auto-measured — no h needed
  "font": "display",                  // display | sans | mono
  "size": 96, "weight": 900,          // weight: 400 | 500 | 700 | 900
  "color": "#1c1c1c", "align": "left",  // left | center | right
  "lineHeight": 1.25,
  "marks": [ { "s": 0, "e": 2, "type": "hi", "color": "#2bd69b", "alpha": 0.55 } ] }
```
`marks` are hand-drawn accents on the character range `[s, e)`. Types:
`hi` (highlight) · `under` (underline) · `under2` (double) · `ring` (circle) ·
`strike` · `corners` (brackets) · `solid` (thick underline) · `mint` (colored text) ·
`bold`. `alpha` applies to `hi` only.

### shape
```jsonc
{ "type": "shape", "x": 80, "y": 560, "w": 400, "h": 240,
  "shape": "rect",                    // rect | ellipse | triangle | star | line
  "fill": "#fffdf8",                  // null = no fill
  "stroke": "#1c1c1c", "strokeW": 3,  // optional outline
  "radius": 16 }                      // rect corner radius
```

### sticker (hand-drawn doodles)
```jsonc
{ "type": "sticker", "x": 860, "y": 120, "w": 120, "h": 120,
  "kind": "spark",                    // arrow | spark | check | cross | squiggle | stripes
  "color": "#1c1c1c" }
```

### image
```jsonc
{ "type": "image", "x": 100, "y": 300, "w": 500, "h": 400,
  "asset": "a1",                      // key into top-level assets
  "ox": 50, "oy": 50 }                // cover-fit focal point, %
```
Images must be embedded via `assets` as `data:image/*` URLs — remote URLs are not
fetched (CORS + export-tainting). AI-authored designs typically use text/shape/
sticker only; humans add photos after import.

## Brand palette (suggested, not enforced)

mint `#2bd69b` · mint-dark `#179d72` · cream `#faf6ea` · bone `#f8f2e2` ·
ink `#1c1c1c` · grey `#b9bdb9` · white `#fffdf8` · red `#d9573c`. Any CSS color works.

## Handing a design to a user (import deep link)

Encode the design JSON as **base64url** (UTF-8; `+`→`-`, `/`→`_`, no `=`
padding) and give the user:

```
https://studio.clawify.dev/#/i/<base64url>
```

Opening it shows an import preview; on confirm the design lands in a project
with every element editable. Nothing is uploaded — the design travels inside
the link. Links are capped at 300 000 characters; designs with embedded images
usually exceed that, so save those as a `.clawify.json` file instead and let
the user drag it into a project.

## Other ways in

- **File import**: drop or pick a `.clawify.json` in any project.
- **Paste**: the in-app ✦ AI 設計 dialog accepts pasted JSON and carries a
  copy-ready prompt that teaches any chat AI this format.
- **MCP server** (for agentic tools): `npx -y clawify-studio-mcp` — tools
  `get_design_format` (this spec) and `create_design` (validate + get the link).

## Versioning

Additive fields need no bump; breaking changes increment `clawify`, and
importers keep reading old versions.