yoshida yoshida
Open the editor

Docs Format

Formatting and Schemas

On this page

Canonical formatting (yoshida fmt)

Every tool writes JSON the same way, so files never churn between the CLI, the editor and the server.

  • 2 spaces indent, LF line endings, trailing newline.
  • One property per line, except that an object containing only scalars, or an array containing only scalars or only arrays of scalars (such as [x, y] points), stays on one line when the whole line fits in 100 columns. The line length counts the indent, the "key": prefix and the value, in UTF-16 code units. So box, at, stroke and most params sit on one line, while layers spread out.
  • Key order is kept exactly as written; the formatter never reorders keys. The editor writes id and type first in new layers and keeps the order of existing ones.
yoshida fmt my-cards            # rewrite the project's JSON files
yoshida fmt my-cards --check    # list files that would change; exit status 1 if any

You can also pass a single file. See Command Line. CI runs fmt --check on the examples, see CI and Deployment.

In the editor, the builder changes the parsed design and writes it back with the same formatter, so the JSON view always matches. See Builder.

Comments

JSON has no comments. Use the note field (every layer, the design, the manifest and params accept one) for comments.

JSON Schemas

Schemas for editors live in schema/ of the repository (JSON Schema draft 2020-12):

FileFor
schema/design.schema.json*.design.json
schema/component.schema.jsoncomponent files for include
schema/defs.schema.jsondefinitions files for import
schema/cards.schema.json*.cards.json
schema/yoshida.schema.jsonyoshida.json

Add a $schema key at the top of a file (adjust the relative path):

{
  "$schema": "../../schema/design.schema.json",
  "format": 1,
  "name": "My design"
}

or map the file patterns to the schemas in your editor's settings (in VS Code, json.schemas). The core ignores the $schema key.

The schemas give autocompletion and structural checks. They cannot check expressions, references between layers or card values against params; yoshida check does that.

For AI agents: llms.txt

Two plain-text files describe yoshida for AI agents and other tools that read text rather than a website:

FileWhat it is
/llms.txtA short index in the llms.txt layout: what yoshida is, and a link to every docs page with its one-line description
/llms-full.txtThe reference on one page: project files, params, every layer type with its fields, the expression language with every function, the command line help, the diagnostic codes and a complete small project

Point an agent at llms-full.txt before it writes a design, and let it run yoshida check on the result. The same two files are in the root of the repository, next to AGENTS.md (how to build and test the code), and in the root of every release zip.

Both are generated by node scripts/llms.mjs from the JSON Schemas, the editor's function catalog, the CLI's help text, the diagnostics page and the docs sidebar, so they cannot describe a field or function the tool does not have. CI runs node scripts/llms.mjs check and fails when a source changed without them.

↑↓ to moveEnter to openEsc to close