# Makeables cards

Keep new lettering, logos, shapes and imported patterns as separate editable
layers. A raster reference remains raster; do not flatten newly authored text
into that image. For a coordinated kit and its mockup, load the `kits` guide.

A card is the shared layered design document with `"product": "card"`. Create and render artwork in the terminal, or use the live Makeables studio for shaders, materials, light and manual editing. No account is needed. Card artwork does not require a portrait, participant name, card number or banking details.

Read the art direction section below before creating or restyling a card: it
sets the visual language, the physical stock and the foil and relief finishes,
with real references and a quality review.

## Default credit-card art direction

For a new credit-card design, deliver a complete, editable banking identity
across both faces. Include an issuer name and wordmark or symbol, chip,
contactless and payment-network mark by default. Treat this as a bank brand
designer's composition: the functional marks belong to the design from the
first draft.

- Use the bank and brand assets the user supplies. If no issuer is specified,
  invent a fictional bank with an original name and visual identity suited to
  the brief; state that choice briefly and proceed. Do not pick a random real
  bank. The issuer is distinct from Visa, Mastercard or another payment network.
  Honor a requested network; otherwise choose one supported network deliberately.
- Establish a clear visual direction, restrained palette, typographic hierarchy
  and recognizable brand motif. Coordinate the wordmark, chip finish,
  contactless ink and network treatment with the artwork. Use supported
  `brand`, `white` or `black` network variants for contrast; keep marks legible
  and recognizable.
- Compose spacing and hierarchy with the actual marks visible. Give the issuer
  a clear position, balance the chip and contactless symbol, and reserve room
  for the network and Wallet number area. Resolve collisions by adjusting the
  composition instead of shrinking every element.
- Design the reverse as part of the same identity, with its own layout and
  hierarchy. Carry through typography, palette and a brand motif; avoid a blank
  back or a duplicate front. Do not invent account numbers, cardholder names or
  security codes to make the design look finished.
- Choose materials and effects to support the direction. Protect critical type
  and marks from material color shifts where needed; keep contrast readable
  under lighting. Use editable layers for branding, marks and decoration, and
  preserve their roles with meaningful names.
- Before presenting, inspect both faces at full size and thumbnail size with
  the marks enabled. Refine color balance, spacing, hierarchy and contrast;
  also inspect the material preview when using live materials. Save the
  complete editable document and describe the issuer and visual direction
  briefly.

Explicit user direction takes precedence. Artwork-only requests do not require
bank branding. For a focused edit or remix, preserve the existing identity,
original SVG elements and requested scope; do not redraw source artwork,
rebrand it or add duplicate marks to satisfy this default. Add missing banking
elements when the user asks to develop that artwork into a complete credit-card
design.

## Editable styles

```sh
makeables styles list --product card
makeables new card --style pearl --out card.json
makeables material set --file card.json --params '{"surface":"chrome","roughness":0.2,"iridescence":0.4,"speed":0.3}'
makeables layer list --file card.json
makeables layer set --file card.json --id title --params '{"text":"YOUR DIRECTION"}'
makeables render --file card.json --out card.png
```

There are 23 styles, each with front and back. `pearl`, `noir` and `sol` use native
layers. The other 20 preserve their actual gallery SVG elements and groups:
`afterimage`, `blue-hour`, `checkpoint`, `crafter-station-private`,
`dream-sequence`, `electric-bloom`, `extra-life`, `form-study`, `garra-29`,
`hunter-license-1999`, `hunter-license-2011`, `hunter-license-green`, `interval`,
`moon-rabbit`, `side-quest`, `soft-signal`, `solstice`, `streak-guardian`,
`system-dialog` and `vibecoders`. Each has a distinct, editable reverse.

Typography, shapes, graphics, gradients, live effects and card marks remain
editable. Inspect `makeables schema --json` before composing complete layers in
the JSON; validate after changes. Save the entire document, not just a screenshot.

### Original SVG elements

Curated fronts use `kind: "svg"` layers with readable `name`s, inert SVG `nodes`
and a `sourceBox`. Shared gradients, filters, masks and source credits live in
`svgSource`. Keep these definitions and original image bytes when editing.
Change `x`, `y`, `w`, `h`, `rotation`, `opacity` and `visible` on the layer;
its original geometry is transformed relative to `sourceBox`.

The `colors` map replaces a source paint, including referenced gradient stops,
only in that layer:

```sh
makeables new card --style solstice --out solstice.json
makeables layer set --file solstice.json --id source-16 --params '{"colors":{"#ffd98a":"#a8eaff"}}'
```

The web inspector exposes group palettes, child-element selection, SVG text,
fill, stroke, opacity, geometry and original path data. Edit text only on actual
SVG text nodes; outlined lettering is a path. Embedded raster illustrations
remain images with editable placement and size, not invented vector parts.
`protectMaterial: true` preserves a layer's ink colors under the material;
`false` lets the coating affect it. No front is redrawn or flattened to make it
editable.

Each card sits on a physical `stock`: omit it for coated print, or use
`metal`, `holographic` or `soft-touch`. Any layer can take `finish: "foil"`
(both faces) or `finish: "raised"` (front only); the flat artwork does not
change, only the live material. See the art direction section for when to use each.

Coated surfaces are `satin`, `prism` or `chrome`, with roughness 0–1, iridescence 0–0.65
and speed 0–1. Effect layers support ribbons, contours, orbits, grain and
chromatic-flow, each with three colors, scale and opacity.

## Live materials and natural-language revisions

Follow the core guide's preview order: embedded Makeables MCP App, built-in
browser, then CLI + inline image. For the built-in browser path, start
`makeables studio start --product card --no-open --json` and open its local
session URL with the host's actual browser-panel capability. Keep that process and tab
alive for revisions. For a checkout use `--site http://127.0.0.1:<port>`.

Discover `studio tools`, inspect state and catalog, then edit with the returned
revision. The shared tools retain their `badge_` names for both products:
`badge_inspect` returns the card styles and card constraints; `badge_edit` selects
a style, patches material/backgrounds/layers or replaces the card document;
`badge_view` changes face and motion. `badge_library` saves locally and
`badge_export` downloads JSON or a material preview PNG. The Preview canvas must
be visible before exporting its material. Import a terminal JSON through the UI,
or use `badge_edit` replace after inspecting its schema and revision.

In the editor, **Edit** provides handles and the number guide; **Preview** uses
the shared WebGPU material renderer, with pointer lighting and tap-to-flip.
**Artwork PNG** downloads flat full-bleed artwork. **Preview PNG** includes the
material and studio framing. GPU-unavailable devices show a labeled static
fallback. Never promise animated materials in Wallet or in a PNG.

Check both faces, text contrast, card marks and the number area after edits.
Keep the same preview open and save JSON after each accepted direction.

## Gallery artwork and stickers

```sh
makeables designs list
makeables new card --design checkpoint --out card.json
makeables layer add --file card.json --sticker petdex:boba
makeables layer set --file card.json --id source-59 --params '{"colors":{"#35e3b0":"#a8eaff"}}'
makeables render --file card.json --out card.png --overwrite
```

After every render, open `card.png` with your image viewer and look at it before describing it. Show the ready preview and offer the three choices below. For an iteration, adjust with `layer set` and render again.

## A card for a person or brand

```sh
makeables new card --blank --name "Builder" --out card.json   # chip, contactless and network only
makeables layer add --file card.json --sticker refs/logo.png --relative-to cwd
makeables layer add --file card.json --kind text --params '{"text":"Builder","font":"display","size":96,"x":80,"y":560,"w":700,"h":120,"align":"left"}'
```

Catalog styles carry their own issuer, copy and credits; use them only when the
user picks one. Check every rendered word against what you wrote.

## Full-bleed art and the back

Both faces work the same way. A face's base color is a `background` op; art that
covers the whole face is an image layer with `fit: "cover"` and
`background: true`, boxed to the full card, placed first so later layers draw on
top. `--render` renders both faces and returns their `.view.jpg` in one call:

```sh
node make-image.mjs --fit card.json --prompt "..." --out art.png      # framed to the card; prints its op
makeables layer batch --file card.json --render --ops '[
  {"add":"sticker","src":"art.png","params":{"id":"art","x":0,"y":0,"w":1200,"h":756,"fit":"cover","background":true}},
  {"background":"#05060f","side":"back"},
  {"add":"sticker","side":"back","src":"art-back.png","params":{"id":"art-back","x":0,"y":0,"w":1200,"h":756,"fit":"cover","background":true}},
  {"add":"text","side":"back","params":{"id":"tagline","text":"Power up. Ship it.","color":"#ffffff"}}
]'
```

Look at both views it returns before the next change. Images over 2 MB are
shrunk to fit; JPG, PNG, WebP and SVG all work.

## Canvas and rules

- The card is 1200 × 756 units. `x`/`y` is a layer's top-left corner and `w`/`h` its size. Pass negative numbers with `=`, as in `--rotation=-12`.
- The lower-left card-number area (x 64 to 470, y 615 to 715) is reserved for Wallet's masked number. New or moved foreground layers must avoid it. Original SVG layers may keep their exact original placement, and full-bleed backgrounds may cover it; conversion never moves source artwork to satisfy the guide.
- `layer list` shows every layer; later layers draw on top.

## Stickers

- `petdex:<slug>` uses a bundled Petdex sprite such as `boba`, `cache-capy` or `prompt-penguin`. New stickers go in the next free corner.
- A local PNG, JPG, WebP or SVG (larger than 2 MB is shrunk to fit; SVG is rasterized, so a brand logo goes in as-is) is embedded in the document, so `card.json` opens anywhere, including the web studio at makeables.dev/make/card.
- Remote URLs are refused; download the image first and credit its author.

## Card marks

Pearl, Noir and Sol include chip, contactless and network `card-mark` layers with ids `chip`, `contactless` and `network`. Curated SVGs keep their existing source marks without adding duplicates; the Card details panel can add native marks. Change native marks with `layer set --params`:

- `slot`: chip `middle-left` or `upper-left`; contactless `upper-right` or `middle-right`; network `lower-right` or `upper-right`. The box follows the slot.
- `color` (chip, contactless): one of `#d9b875`, `#c7d0d9`, `#c77955`, `#ffffff`, `#202024`, `#447bd1`, `#cf4b54`, `#50a581`, `#9b72c6`.
- `network`: `mastercard`, `visa`, `amex`, `discover`; `colorMode`: `brand`, `white`, `black`; `visaVariant`: `boxed`, `plain`.
- Hide a mark with `{"visible":false}` or delete it with `layer remove`.

The exported PNG is artwork only. It never changes a real card, and it must not contain account numbers or cardholder names.

## From a prompt, reference image or existing SVG

Keep this workflow in `cards`; there is no separate remix skill. Use the user's
source and requested scope. A faithful reference adaptation preserves its
composition, identity and marks. Remove personal card numbers, cardholder names,
expiry dates and security codes from artwork; do not strip a requested chip or
logo merely because the input is a reference.

- **Existing SVG:** keep its original paths, groups, definitions and embedded
  image bytes. Import it without retracing:
  `makeables new card --file reference.svg --name "Card title" --out card.json`.
  Supported elements become SVG layers; collective effects and linked elements
  stay grouped to preserve rendering. Unsupported SVG elements produce a clear
  error: edit the source instead of silently flattening or redrawing it.
- **Raster reference:** inspect the source, crop deliberately and preserve its
  proportions. `new card --file reference.png --out card.json` embeds an editable
  image layer using contain; its pixels are not separately editable vectors.
  For a measured rebuild or selective trace, load `makeables skills get images`
  for the bundled local preparation, measurement, glyph and comparison tools.
  Trace only the content that benefits from it; photos and gradients may stay
  embedded when fidelity matters more than a pure vector result.
- **Prompt alone:** establish a direction and create an original design. For an
  identifiable reference object, use supplied references first. Research only
  when needed, permitted and supported by available tools. A no-web request or
  unavailable search is not an error loop: continue from supplied materials,
  disclose uncertain provenance and ask only for a missing essential reference.
- **Portrait objects:** compose the whole object upright on 756 × 1200, then use
  `makeables image rotate --file portrait.svg --out card.svg`. Its top goes left
  by default; `--params '{"top":"right"}'` switches sides. Preserve the full
  composition rather than stretching it into landscape or cropping to a logo.
- **Attribution:** retain supplied credits; record owner/source/permission for
  added assets. Label fan concepts accurately. Do not invent official origins
  for an unverified colorway, affiliation, exact glyphs or missing details.

Validate SVGs with `makeables validate --file card.svg --out preview.png`;
validate editable documents with `makeables validate --file card.json`.
`makeables image compare --file card.svg --ref reference.png --out compare.png`
creates a side-by-side comparison. Inspect proportions, colors, lettering,
patches, boundaries and both faces. Design a coordinated reverse as part of a
new card brief; preserve the requested scope for a focused source edit.

## Finish with a choice

When the first card preview is ready, show it and the editable file, then ask
naturally in the user's language: **“¿Quieres seguir iterando, publicarlo en la
galería o instalar el diseño en tu celular?”** Do not offer only more edits.
If the user already chose one of those actions for this exact version, follow
that choice without asking again.

- **Iterate:** keep the current document and preview, make the requested change,
  then save and show the updated faces.
- **Gallery:** run `makeables submit --file card.json --dry-run`, then
  `makeables submit --file card.json --yes` after the user's approval. Layered
  cards, original SVGs and portable Makeables packages use the same reviewed
  workflow as badges. Add `--title`, `--credit`, `--credit-url` or `--category`
  when needed. `makeables studio save` preserves stored assets from the editor.
  The browser alternative is https://makeables.dev/submit. Keep all layers,
  source vectors and both faces; do not rasterize the card into an SVG wrapper.
  Report **pending** as awaiting review and **approved** as public. Recover with
  `makeables submit status --file card.json` using the same metadata flags.
- **Install on the phone:** load `makeables skills get wallet` at that moment and
  follow it with the chosen document. It applies artwork to an existing Wallet
  card using a Mac and a USB-connected iPhone. Creating a card does not itself
  authorize a device write. Keep the complete artwork and its original backup.

## Art direction

This sets the visual bar and the physical finish. The sections above keep the
functional rules: marks, the number area, both faces and the finish choice.

### The visual language

A great card reads as **one object with one idea** from across a room. Pick a
single motif that belongs to the subject: a sun on a dune, a licence emblem, a
moon with one rabbit, an arch and a column. Give it a clear position, usually
off-center, and leave most of the card calm. The card is a small canvas held in
a hand. Density reads as noise at 85.6 mm.

- Three to five major shapes. Remove anything that does not explain the motif.
- One palette of two or three inks plus the stock. Tie every color to the
  subject; never reach for a default fintech gradient.
- The issuer wordmark is drawn, not typed. It gets a deliberate weight, size
  and position, and it is the first thing you finish with foil or relief.
- Small type is a detail, not a layout. At most two supporting lines.
- The reverse continues the identity with its own composition: one motif from
  the front, reframed, plus quiet functional text. Never a copy of the front.

Avoid: generic purple-blue gradients, glassmorphism panels, random waves,
stock "circuit" patterns, fake numbers or names, every element centered,
decorative filler added to fill space, and sparkle across the whole card.

### Choose the physical card first

The finish is part of the idea, not a coat of paint added at the end. Decide
the stock with the motif, then mark which layers catch the light.

| Stock | `material.stock` | Use it when | Avoid |
| --- | --- | --- | --- |
| Coated print | omit it | Illustration and scenes that should read as printed color; `surface` still picks prism, satin or chrome | Scenes that need a metal feel |
| Brushed metal | `metal` | Licences, private or premium editions, monochrome and typographic cards; the print becomes an anodized tint | Busy full-color illustration, which turns grey |
| Holographic | `holographic` | Light, spectrum and night subjects; the rainbow only appears where the light band passes | Cards whose colors must stay exact |
| Soft-touch matte | `soft-touch` | Paper, Bauhaus, pixel art, calm pastel and editorial cards | Subjects that should shine |

A stock is only the starting material. Tune it to this one design with
`material.optics`, so the light behaves the way the subject does:

| Optic | What it does | Derive it from |
| --- | --- | --- |
| `grain`, `angle`, `center`, `grainStrength` | Brushed or laminate grain: `linear` at an angle, `radial` rays or `concentric` rings around a center (0–1 card coordinates) | The design's own geometry: rings around an emblem, rays from a sun, lines along a sash |
| `diffraction` | `radial` makes the highlight and the holographic spectrum ring out from `center` | A single luminous motif: a sun, a moon, a flower core |
| `spectrum` | Three colors the holographic laminate cycles through | The palette of the art, never a generic rainbow |
| `foil` | The foil color for every foil layer | Gold for heritage, copper for warm paper, silver for steel; omit to keep each ink |
| `light` | Color of the moving highlight and edge | The scene's light: cold dusk, warm lamp, moonlight |
| `sparkle` | Fine glints that catch the tilt | Stars, pollen, city windows; zero for calm designs |
| `relief` | Depth of raised layers | Deep for letterpress, shallow for enamel |
| `sheen` | From a sharp streak (0) to a broad glow (1) | Sharp on metal and licences, broad on pastel and paper |

Write the reason in one line next to the recipe. If two cards share the same
optics, one of them is not finished yet.

```sh
makeables material set --file card.json --params '{"stock":"holographic","optics":{"diffraction":"radial","center":{"x":0.65,"y":0.64},"spectrum":["#ff3d9a","#ff8a3d","#ffd166"],"sheen":0.35}}'
```

Then assign finishes to layers with `finish`:

- `foil`: mirror ink in the layer's own color that flares as the light moves.
  Use it on one to four elements: the wordmark, a rim or frame, one motif
  highlight such as a sun, a heart or a star. Works on both faces.
- `raised`: embossed relief with a lit and a shadowed edge. Use it on the main
  shape or the wordmark. Front face only.
- Leave everything else as print. A card where everything is foil has no foil.

Keep critical marks legible: the chip, contactless and network marks stay
protected ink (`protectMaterial`), and the lower-left number area stays calm.

```sh
makeables material set --file card.json --params '{"stock":"metal","roughness":0.3}'
makeables layer set --file card.json --id wordmark --params '{"finish":"raised"}'
makeables layer set --file card.json --id sun --params '{"finish":"foil"}'
```

For original SVG layers, set `finish` on the named layer; the source vectors
stay untouched and the flat artwork does not change.

### Real references

Every curated card has a physical recipe you can study and reuse. Open it with
`makeables new card --style <slug> --out ref.json`, then `layer list`, or see
its flat art at `https://makeables.dev/designs/<slug>/preview.webp`. Pick by
the idea, not the colors:

- `crafter-station-private`: black brushed metal, gold foil rims, raised wordmark.
- `vibecoders`: aluminium, raised display type, foil brackets.
- `hunter-license-1999`: vermilion anodized metal, gold foil surround, raised emblem.
- `solstice`: holographic diffraction radiating from the sun in its own magenta-to-gold spectrum, foil sun and dune rims, raised dunes.
- `hunter-license-2011`: black steel with rings turned around the emblem and ice-blue light.
- `moon-rabbit`: a halo of light ringing the pearl-foil moon, twinkling stars, a raised rabbit.
- `form-study`: soft-touch paper, raised Bauhaus shapes, one foil intersection.
- `moon-rabbit`: coated satin, foil moon and stars, raised rabbit.

When a model generates artwork, attach two or three of those preview images as
references and label their role. A text-only description of a style is not a
reference.

### Prompt scaffold

Replace every bracket. The finish plan is written before the image exists.

> Use case: flat artwork for a landscape bank card, 1200 × 756, full bleed.
> Images 2–3 are references for composition and restraint only; do not copy
> their text, brands or motifs.
> Idea: [one sentence: the single motif and why it belongs to this subject].
> Composition: [motif position, calm areas, where the wordmark sits]. Leave the
> lower-left area (x 64–470, y 615–715) quiet for the card number.
> Palette: [stock] plus [two or three inks tied to the subject].
> Restraint: three to five major shapes, flat color, clean edges, no filler.
> Flat head-on artwork, no perspective, mockup, hand, shadow, text other than
> "[exact issuer name]", fake numbers, names, chip or network logo.
> Avoid: generic gradients, glassmorphism, random waves, sparkle everywhere,
> busy textures, baked lighting or reflections.

Then add the chip, contactless and network as card marks, and the finishes as
layer settings. Do not paint shine into the artwork: the live material draws it.

### Acceptance before showing the result

- The idea reads at gallery thumbnail size, about 270 px wide.
- At full size the wordmark, marks and number area are clean and legible.
- In the live preview, foil flares when the light passes and settles back;
  relief shows one lit and one shadowed edge; the stock reads as what it is.
- Tilt fully in both directions: no text disappears into a highlight.
- Both faces share the identity and each has its own composition.
- The flat Artwork PNG still looks finished without the material.

If a check fails, make the smallest change and look again. Taste is not
guaranteed by a prompt; comparing against the references is part of the work.