Craft

Layouts

A layout decides how every file of a type looks on its page: the character sheet, the quest card, the item page. The schema says what a file stores. The layout says how that is arranged, and which values players can change with a tap during play.

Think of a layout as a lens for play. Design it around what a player needs to recognize (who is this?), decide (what can I do?) and change (spend a spell slot, tick a wound), not around showing every stored field.

How it is used

  • A layout belongs to the file type. Changing it restyles every file of that type at once, and it touches none of their content.
  • A type with no layout shows its files field by field. That is fine for simple types and worth replacing for anything players look at often.
  • The layout is saved with the type, so the type's version history keeps every earlier layout. To go back, open the type's Version History tab and restore the version you want.
  • Players see the layout in the game too. Values a layout makes editable can be changed by players during play, and the GM reads the same fields.

Changing a layout

The layout lives in the file type's Layout tab.

Edit Manually opens the Layout Designer: components, a live canvas of one of your files, and an inspector. Apply layout saves. Or use Edit with AI, or ask Orbit for the sheet you want.

Doing it well

  • Start from the schema. Before designing, open the file type's Schema tab and look over its fields. Every field you can show is there, and a path that doesn't match a field shows nothing, with no error.
  • Match the project. Look at the layouts of the world's other types first and keep their style.
  • Make play-time values one tap. Anything that changes during play should be editable where it is shown: dots or track boxes for small pools, a stepper for hit points and ammo, a toggle for flags, condition chips for status effects, a clock for countdowns.
  • One array and a repeat, never numbered copies. Show a list of things by repeating one element over an array field, not by writing an element per item. It keeps working as the list grows.
  • Variants go in sections. Blocks that only some files need (a subclass's features, a faction's perks) go in named sections, picked by a section switch, not in the main layout behind visibility conditions.
  • Group by task. A long sheet reads better as two to five tabs (identity, play stats, resources, inventory, notes), with what's always needed kept above the tabs.
  • Leave the GM's secrets off the sheet. A suspect's secret or a case's truth stays a field the GM reads, not something the sheet puts in front of players (it hides nothing: see visibility).
  • Show each value once. The same number in two places drifts out of sight when one is edited.
  • Match the component to the field. Long text gets Markdown, stats get a stat grid, references to other files get a reference grid or a select, and a picture gets an image header.
  • References start in the schema. A layout component that picks files of a type needs the schema field to be a reference field to that type, so computed fields, backlinks and the GM can follow it.
  • Keep it small. A layout is sent with every file of its type, and one over 1 MB is refused. A good character sheet is a few hundred elements. Show many records with one reference grid or one repeat, never one element each.

Reviewing a layout

To review or improve how a type looks:

  1. Read the schema and the layout together. Every judgment pairs a field's role (stored, computed, a reference, display only) with how the layout shows it.
  2. Check every binding both ways. Each path the layout reads must be a real field: a stale path shows nothing, so treat it as broken. Then list the fields the layout never shows, and decide which are hidden on purpose and which a player would miss.
  3. Check what changes during play. Each such value should save in one tap where it is shown. A tracker over a computed list needs an edit path into stored state (see the spec).
  4. Check structure. Numbered copies become a repeat. Variants behind visibility conditions become sections. Values shown twice are shown once. A long sheet becomes tabs.
  5. Report in plain words, outcomes first. "Spell slots become dots you tap during play", "the sheet fits into three tabs". No element keys or JSON. Say that a layout change moves no content.
  6. Check after saving. Open a file of the type and confirm each new binding shows a value. For a conditional part, check a file where the condition holds and one where it doesn't.

Mistakes

  • A tidy-up that takes away a control. A sheet is where the file is edited. Moving or restyling a field's control is fine; swapping an editable one (a select, a stepper) for a read-only one needs asking.
  • A path with a typo. It shows nothing, with no error.
  • A child key with no element. That part of the sheet is missing.
  • An element without props. Every element needs "props": {}, even when it is empty.
  • An enum value that isn't listed. aspectRatio is "ultrawide", never "ultra-wide". Copy values from the component reference.
  • An edit path whose display doesn't read the written value back. The click saves, but the sheet never shows it.
  • A digit-only key in an edit path. /resourceState/3/current writes into an array. Use keys like rage or slots-1.
  • Pictures as data: URLs. They are refused. Use an uploaded or generated image's URL.

Reference

  • Layout components: Every component a layout can use, with its props, types and an example.
  • The layout spec: The layout format: elements, data binding, visibility, repeats, edit paths, sections and references.