Skip to content

Card layout language

A card design is one JSON document. The same card can also be written as HTML and CSS; both become the same thing inside the app. For what a card design is, see Card and row designs.

The design document

A design belongs to one place: a collection, a view, a host page or an entry.

Key Holds
version, contract the file version and the name-tag contract version
place kind (collection, view, hostPage or entry) and its id
base the design it builds on (optional)
background the place’s background (same shape as the theme)
parts looks for any name tag in this place
card the card design (below)
entryPage the entry page design: layout, pieces (its sections, such as the properties), parts
rules value rules for the place
when size and condition rules for the place

The card

Key Holds
layout the layout kind and its settings
items what the card shows
parts looks for the parts inside the card (its own checkbox, for example)
on what happens on an event
when size and condition rules
rules value rules

Layouts

kind Use it for Example
stack items one under another title, then date, then tags
inline items side by side checkbox, title, time
grid named areas, like ["check title title", "gif gif gif"] a dashboard-style card
overlay items on top of each other, each placed with align a checkbox over a picture

align values: topLeft, top, topRight, left, center, right, bottomLeft, bottom, bottomRight.

Groups nest, so any layout can hold another. The key that holds a grid’s named areas is not decided yet.

Items

Item What it shows Key
Field any property, shown and edited with its standard editor, in any display style its kind offers (a checkbox as a ring, a number as a big figure) field: the property name
Text fixed text, or computed text like “3 days left” not decided yet
Image an uploaded file, or an image property image: asset:…
Icon an icon from the theme’s set not decided yet
Group a layout inside the layout not decided yet
Button a button that makes one change not decided yet
Spacer empty space not decided yet

Item settings shown in the plan: align, size, play (for an animated image: always), parts, moments and on.

Fields are stored by id, shown by name. You write "Done"; the app stores the property’s id. Renaming the property updates the files and never breaks the design.

Text with values is written {{ @Streak }} days. The value is filled in once and shown as plain text. A value that holds {{ … }} is shown as written, never filled in again.

Size and condition rules (when)

Condition Values
screen phone (under 600 px), tablet (600–1023), desktop (1024 and up), wide (1440 and up), or your own numbers
cardWidth small (under 240 px), medium (240–479), large (480 and up), or min and max numbers
input touch or mouse (touch has no hover, so parts get pressed)
orientation portrait or landscape
motion reducedMotion
colour mode light or dark
"when": [
{ "screen": "phone", "items": [{ "field": "Done", "align": "center" }] },
{ "cardWidth": { "max": 239 }, "parts": { "checkbox": { "size": 22 } } }
]

Card-width rules work for cards and blocks. Table and list rows follow the view’s width. The exact keys for input, orientation, motion and colour-mode conditions are not decided yet.

Value rules (rules)

A value rule changes looks when the entry’s values match. Each rule has an if expression and the parts to change. Examples: “when Done is ticked, fade the card”; “when overdue, a red border”.

Rules on the entry’s own values update in the same frame. Rules on linked entries or totals update a moment later. Rules on today’s date update once at midnight.

Events and actions (on)

Events: click, longPress, change (a value changed, whoever changed it), hover, appear (scrolled into view), open (a page opened).

Action What it does In a design someone else made
play plays a built-in or your own animation on
toast shows a toast.custom with your own words on
open opens the entry, a view, a day, or the entry’s peek on
a button’s change sets the value it names, adds the tag it names, starts or stops its timer, or starts recording on a JSON property that records (“Start run”) off until you turn it on
openLink opens an https link from one of the entry’s Text properties with the Link format, in your browser, after the “You’re leaving Kaizendex” screen off
askAI asks the AI about this entry; any change it suggests needs your OK off; someone else’s question gets no web tools
runScript runs a card script off

Each action can have a condition:

{ "field": "Done",
"on": { "change": [
{ "play": "confetti", "if": "@Done == true" },
{ "toast": "Well done!", "if": "@Done == true" }
] } }

Never from a design: deleting, moving to the Trash, moving to another collection, sharing, privacy, plans, settings, signing out, or writing a value built from other values. A change a design makes never fires another design’s change event, so designs cannot start loops.

A custom toast has no buttons and no links, shows at most once every 3 seconds, and its words come from the design, never from a value.

The same card in HTML and CSS

A skin on feed.card for the Habits feed:

<div class="habit">
<img asset="smile" class="smile" alt="">
<field name="Done" class="done" mark="star" tick-effect="confetti"></field>
</div>
.habit { position: relative; height: 160px; display: grid; place-items: center; }
.smile { width: 96px; }
.done { position: absolute; top: 10px; right: 10px; }
.done [data-part~="checkbox"] { width: 28px; height: 28px; }
@container card (width < 240px) { .smile { display: none; } }

Every card is a CSS container called card. What HTML and CSS may hold is in HTML and CSS rules.