yoshida yoshida DEV
Open the editor

Docs Format

Designs

On this page

A design file (*.design.json) describes one card layout: the canvas, the fonts, the parameters a card can set and the layers that are drawn.

{
  "format": 1,
  "name": "Example",
  "canvas": { "width": 1200, "height": 1800, "background": "#00000000" },
  "fonts": { "body": "assets/fonts/Body.ttf" },
  "params": { "title": { "type": "text", "default": "Untitled" } },
  "layers": []
}
FieldKindRequiredDefaultMeaning
format1yesSee Project Layout and Manifest
nametext literalyesDisplay name
notetext literalnoComment
canvas.width, canvas.heightnumberyesPixels. May use params, but not % units and not layer references
canvas.backgroundcolorno#00000000Transparent by default
canvas.dpinumbernononePrint resolution, stored in PNG files and used for the PDF page size. See Saving, Images and Privacy
canvas.bleednumberno0Pixels on every side that are cut off after printing. Crop marks and the PDF trim box sit this far inside the edge
fontsobject of name to path or { path, note }no{}Font families for text layers
paramsobject of name to paramno{}See Params
importarray of pathsno[]Definitions files whose params and consts this design takes. See Sharing params and constants
constsobject of name to valueno{}Named values. See Constants and functions
functionsobject of name to functionno{}Named formulas with arguments. See Constants and functions
layersarray of layersyesDrawn in array order, first is bottom. See Layers

Unknown top-level fields are error 1101.

The word kind (number, bool, color, text, path, enum, ident) says how a JSON value in a field is read. See Expressions.

Canvas

width and height are numbers in pixels. Because they are expressions, a design can scale with a param:

"canvas": { "width": "421 * scale", "height": "614 * scale" }

The canvas cannot use %, vw or vh (it is being defined, error 3006) and cannot refer to layers. The limit is 10000 x 10000 pixels (error 5001). The background is a color expression; transparent by default.

Fonts

"fonts": {
  "body": "assets/fonts/Body.ttf",
  "title": "assets/fonts/Title.otf"
}
  • Names follow the identifier rule [a-z_][a-z0-9_]*.
  • Values are project paths to TrueType or OpenType files.
  • A value can also be an object with a path and an optional note, for example "body": { "path": "assets/fonts/Body.ttf", "note": "Body text for rules cards" }. The note is a comment for editors and does not change the rendering. A missing path is error 1102, and any other key is error 1101.
  • A font named default is built in (Lato, SIL Open Font License). You may override it by declaring default yourself.
  • A text layer picks a font with "font": "body". A name that is not declared is error 4004.
  • A font file that is missing or not a TrueType/OpenType font is warning 4005 and the default font is used for that name.
  • Characters the font does not contain are drawn with the bundled default font, and if that has none either, with the bundled symbol font (arrows, shapes, stars, check marks, dice faces, dingbats). Only characters none of them has are drawn as boxes, and warning 4003 says so.

In the editor, the Fonts window adds entries to fonts when you import a font.

See Layer: text.

Icons

icons names the pictures that text layers with markup put inline with {icon:name}: an object of name to path, or one path with * where the name goes.

"icons": { "steel": "assets/icons/steel.png", "gold": "assets/icons/gold.png" }
"icons": "assets/icons/*.png"

Canvas and card data together

Every card in a set uses the same design. The card supplies values for the design's params, see Card Data. Everything else (layer positions, colors, text) can be an expression that reads those params.

Hand-editing tips

  • Add "$schema": "../schema/design.schema.json" (adjust the path) for autocompletion and validation in editors like VS Code. See Formatting and Schemas.
  • Run yoshida check <project> after every edit; messages carry file, line, column and a hint. See Diagnostics.
  • Run yoshida fmt <project> before committing so files stay in the canonical layout.

↑↓ to moveEnter to openEsc to close