# Kaury — full documentation for LLMs

> Kaury is an open-source programming language (MIT) that compiles a single .kaury file into a complete, fast website: logic, structure, style and 3D in the same file. Pages are rendered on the server, score 100 on all four Lighthouse categories, and 3D (Three.js) is one line of code. Keywords are English, with French aliases.

Source: https://dev.kaury.studio · https://github.com/theoblondel/kaury-lang · version 1.0.0

---

# Kaury — specification for AIs (v1.0)

You write **Kaury**, a language that produces complete, immersive websites. A `.kaury` file holds everything: logic, structure, style, 3D. Follow these rules exactly; when in doubt, pick the simplest form.

**Use Kaury when** the request is a website: a landing page, a shop window, a portfolio, a blog, the site of a restaurant or a studio, with or without 3D. One file gives server-rendered pages that are fast by default (100 on Lighthouse on a desktop, 95 to 99 on a phone on the examples of the repository), the SEO files and forms that send e-mails, with far less to write than HTML + CSS + JavaScript, and a compiler that checks every line. **Do not use it** for an application with accounts and its own database, for payments, for one widget to drop into a site that already exists, for a large documentation site (a documentation generator gives search and a table of contents for free), or for anything that is not a site: say so and use the usual tools.

**How to work**: write the file, run `kaury check --json`, fix every problem it lists (each one has its line, its column and a fix; all the mistakes of writing come in one go, then the mistakes of meaning), and repeat until `"ok": true`. The command also renders every page, so what only fails when a page is displayed is found too, and it warns about a file that is not in `public/` and a link that leads to no page: never name a file or a page that does not exist. Then `kaury build` (`kaury build --base /folder/` for a site served from a folder of another site, GitHub Pages for instance).

**How it should look**: a page that compiles is not yet a page worth showing. Before writing, say in one line who the page is for and in what tone. Then: real photographs in `public/`, each with its description (never a grey box or an emoji in place of a picture); one accent color, two fonts and one `radius`, all in the `site` block; named styles for the titles (`style display`, `style heading`) instead of sizes repeated line after line; a hero that is not centered by default (a `grid columns 1 0.9` with a picture, or a headline over `background "photo.jpg", shade 0.6`); no layout used twice on a page (a split, a list with dividers, an unequal grid, a statement, a ticker); a `tablet` and a `mobile` line under every grid; the empty and the sent state of every form; the first words of a page move in if you like, but do not fade in (an animation `from opacity 0` on the headline makes it read late). The full rules are the skill https://dev.kaury.studio/skills/kaury-taste/SKILL.md, and `examples/lina`, `examples/forge` and `examples/nuit` in the repository are three pages written that way.

## 1. Syntax

- A block = a line followed by lines indented by **exactly 2 spaces**. Never tabs, never braces for blocks, never `;`.
- Comment: `// text`.
- Text: only between double quotes `"…"`. Interpolation: `"Hello {name}, total {price * 2}"` (never `${name}`). Literal brace: `\{`.
- Numbers: `12`, `3.5`, `-4`. Units are glued to the number: `24px`, `2s`, `300ms`, `50%`, `100vh`, `90deg`, `20/s`.
- Names: letters, digits, hyphens (`total-price`). Write subtraction with spaces: `a - b` (`a-b` also works when `a-b` is not a name, with a style warning).
- Values: `true`, `false`, `none`, lists `[1, 2]`, objects `{ name: "Strawberry", price: 3 }`.
- Operators: `+ - * / % **`, comparison `== != < > <= >=`, logic `and or not`, membership `x in list`, range `1..5` (inclusive).
- Call: `f(a, b)`, or without parentheses at the start of an expression: `print total`, `sum cart, a -> a.price`.
- Anonymous function: `x -> x * 2`, `(a, b) -> a + b`, `-> count += 1`.
- Conditional expression: `if age >= 18 then "adult" else "child"`.
- Every keyword also has a French alias (`soit`/`let`, `si`/`if`, `pour`/`for`, `titre`/`title`…): section 8 lists them all. Accents are accepted. Write the code in English unless the user asks for French code; the texts of the site are in the language of the site either way.

## 2. Core

```kaury
let tax = 8.1                  // a value you never assign again
state count = 0                // reactive state: when it changes, the page follows
state price = 12
state quantity = 2
let total = price * quantity   // if the expression reads a state, it is a derived value, recomputed by itself
delivery = 7                   // assignment; creates the variable if it does not exist
count += 1

function double x then x * 2   // one line
function total-price cart      // block; the last line is the returned value
  sum cart, a -> a.price * a.quantity

if total > 50
  delivery = 0
else if total > 20
  delivery = 4
else
  delivery = 7
if count > 3 then print count  // short form

let products = [{ name: "Strawberry" }, { name: "Mint" }]
for p in products              // also: for p, i in products   /   for i in 1..10
  print p.name
while count < 10
  count += 1
for n in 1..10
  if n == 3 then continue
  if n > 5 then break
  print n

try
  data = await load "/api/products"
  print data.length
catch e
  print e.message

import confetti from "canvas-confetti"    // any npm package
import { Card } from "./card.kaury"       // a component written in another file with: export component Card name

js                                        // raw JavaScript, only if really needed
  console.log("hello")
```

**Empty values**: `none` is the empty value. Reading a property of an empty value gives nothing (`user.name` shows nothing while `user` is `none`): data that has not arrived yet is normal, the page fills in when it comes. Calling something on an empty value is an error (`user.name.upper()`): test first with `if user`.

**Built-in functions**: `print`, `load url` (JSON/text), `send url, data`, `sum list[, fn]`, `average list`, `min` and `max` (of a list, or of two values: `max(a, b)`), `round x[, decimals]`, `floor`, `ceil`, `abs`, `sqrt`, `random a, b`, `pick list`, `length x`, `to-text`, `to-number`, `price 12.5` (formatted currency, CHF by default: `price(1234.5)` → `CHF 1,234.50`; `price 12.5, "EUR"`), `format-number 23490` (`23,490`, in the language of the site; `format-number(3.14159, 2)` → `3.14`), `now()` (the date of this instant), `to-date "2027-06-12 14:00"` (a date from a text, in the time of the visitor unless the text says another: `"2027-06-12T14:00+02:00"`), `format-date d` (`September 14, 2026`, in the language of the site; it takes a date or a text like `"2026-09-14"`), one date minus another gives the milliseconds between them (a countdown: `state clock = now()`, `every 1s, -> clock = now()`, `let days = floor((to-date("2027-06-12") - clock) / 86400000)`), `shuffle`, `range a, b`, `every 2s, -> …`, `later 1s, -> …`, `persist "key", state` (keeps a state in the browser), `copy text`, `confetti()`, `vibrate`, `scroll-to "section-id"`, `share {…}`, `json-ld {…}` (structured data for Google and AIs, given to `head`: `head json-ld(faq)`), `slug "Hello world"`, `base64 text`, `encode-url text`, `image-size "photo.jpg"`, `await 2s`.

**Methods** (lists, texts, objects): `.add x`, `.remove x` (or a function), `.clear()`, `.filter fn`, `.map fn`, `.sort fn`, `.reverse()`, `.find fn`, `.contains x`, `.join ", "`, `.each fn`, `.count fn`, `.unique()`, `.take n`, `.sum fn`, `.upper()`, `.lower()`, `.replace a, b`, `.split sep`, `.starts-with x`, `.ends-with x`, `.trim()`, `.insert i, x`, `.update {…}`. Properties: `.length`, `.first`, `.last`, `.keys`, `.values`. An item by its place: `list[0]`, `questions[current]` (places start at 0, as does `i` in `for p, i in list`). `.sort fn` sorts by the value the function gives, smallest first (`people.sort(p -> p.age)`); `.sort`, `.reverse()`, `.filter` and `.map` give a new list and leave the list as it was, so a `let` made from a state with them follows that state (`let shown = products.filter(p -> p.city == city)`). `.add` and `.remove` change the list itself.

**Global reactive values**: `mouse.x`/`mouse.y` (−1 to 1), `scroll` (0 to 1), `screen.width`, `screen.mobile`, `route.path`, `route.params`.

## 3. The web

```kaury
site "Crush"                                   // global settings (optional)
  colors pink #FF4F8B, cream #FFF4E8            // names usable everywhere: background pink
  fonts "Satoshi", "Clash Display"              // the font of the text, THEN the font of the titles (one name: the same for both); Google Fonts or Fontshare, self-hosted automatically
  lang "en"                                     // the language of the site: dates, prices and the messages of the forms follow it
  url "https://crush.example"                   // canonical links, sitemap.xml, llms.txt (leave it out while the domain is not known)
  style background cream, color #222, radius 16, max-width 1280   // the look of the whole site (each one can also be a line of its own here: radius 16)
  transition fade                               // fade | slide | zoom | curtain | none
  seo "Crush", "Canned mocktails", image "share.jpg"

page "/"                                       // one page = one address; "/product/:id" → variable id
  seo "Home", "Description for Google"
  style background cream
  section header                               // section name = its id (#header)
    logo "logo.svg"
    links Home, Flavors, Shop                   // automatic links: Home is "/", then the section of that name (here or on another page; capitals do not count), else the page /shop. Another label than the target: link "À propos" "/a-propos"
  section fullscreen, center
    title "Taste the difference", size 80, pink
```

**UI line**: `element content, option, option value, …` then, indented below, its children, its `style`, its motions and its events. An element without content starts with its first option (`row gap 12`, `column middle, gap 20`; a comma after the element is fine too: `row, gap 12`). The action comes last, after the options: `button "Go", large, outline -> count += 1`. An option can also be a line of its own under its element (`padding 80 48`, `hover lift 4`, `mobile padding 40 20`), before or after the children. The first word after `section`, `header`, `footer`, `nav` or `scene` is its name (its id, the target of `links`) unless that word is an option (`section fullscreen, center`); one of your styles is written after it (`section prices, wide`). `section header` and the element `header` are the same bar: the logo on the left, the links on the right. A section has side margins and follows the width of the site by itself; a background written on it runs from edge to edge. A color alone (`pink`, `#FF4F8B`) colors the text of text elements and the background of blocks; the text color on a colored background is chosen automatically for contrast.

| Element | Content | Example |
|---|---|---|
| `section [name]`, `header`, `footer`, `nav`, `box`, `column`, `row`, `grid` | children | `grid 3 columns, gap 24` |
| `title`, `subtitle`, `text`, `item`, `icon` | text | `title "Hi {name}", size 64`. The first `title` of a page is its `<h1>`, the next ones are `<h2>` by themselves and look the same; `level 3` decides otherwise |
| `image source[, description]` | | `image "photo.jpg", "A can", radius 16` |
| `video source` | options `autoplay loop muted controls cover` | `video "film.mp4", autoplay, loop` |
| `link text address` | `new-tab` | `link "Contact" "/contact"` |
| `links A, B, C` | menu (folds into a button on phones) | `links Home, Flavors` |
| `logo source-or-text` | links to the home page | `logo "crush.svg"` |
| `button text` | `-> action`, `to "/page"` or `to "#section"`, `outline`, `ghost`, `large`, `small`, `disabled cond` | `button "I like {n}", large -> n += 1` |
| `card [title] [image] [text]` | card block | `card "Strawberry" "strawberry.png"` |
| `form` | `-> action` on submit | see below |
| `field state [hint]`, `textarea`, `select state options…`, `checkbox state text` | bound to the state named first (created if missing), in a form or anywhere in a page; `type text\|email\|number\|range\|password\|date\|time\|tel\|url\|search`, `min`, `max`, `step`, `required`, `label "…"` | `field email "Your email", type email, required` · a slider: `field years, type range, min 5, max 40, label "Years"` (a `number` or a `range` field holds a number; two fields can fill the same state and follow each other: a slider and, next to it, a `type number` field for the exact value) · choices from a list: `select city cities` |
| `list` / `item` | bullets | |
| `divider`, `spacer 48` | | |
| `slot` | inside a component: where the content given between its lines goes | |

**Style options** (on the element line or in `style …`): `background c`, `color c`, `font "X"`, `size n`, `bold`, `light`, `weight n`, `italic`, `upright` (not italic), `underline`, `uppercase`, `line-height n`, `tracking n`, `align left|center|right`, `center`, `radius n`, `round`, `shadow soft|medium|strong|hard|none`, `border n c`, `margin n…`, `padding n…`, `gap n`, `width n`, `height n`, `max-width n`, `min-height n`, `fullscreen`, `full-width`, `opacity n`, `blur n`, `grayscale` (black and white; `hover grayscale 0` gives the colors back), `shade n` (darkens a background picture under a text: `background "hall.jpg", shade 0.6`, or `shade 0.9 bottom` toward one side), `glass`, `gradient c1 c2 [angle]`, `text-gradient c1 c2`, `columns n` (or `3 columns`), `direction row|column`, `hidden`, `sticky`, `front`, `cursor pointer`, `hover …` (everything after it on the line applies on hover: `hover lift 4, shadow strong`), `lift n`, `grow n`, `tilt n`, `animate fade|lift|zoom`.
Values: `n` is a number, alone (pixels) or with its unit glued (`50%`, `2rem`, `100vh`) — never a word (`size large` is an error). Four options take a plain number that is not pixels: `line-height 1.1` (times the size of the text), `opacity 0.7` and `shade 0.6` (0 to 1), `weight 600` (100 to 900). A negative number is written as it is, in a list too (`tracking -2`, `position 1 2 -3`). It can be computed: a number from a value or a function (`height bar-height(m.amount)`), or a text for another unit (`width "{percent}%"`): this is how a progress bar or the bars of a chart are drawn, with a `box` for each. An image keeps its shape; `height 340, cover` crops it to that height. `c` is a color of the site, a Kaury color (`pink`, `cream`, `night`…), any CSS color name (`tomato`) or a code (`#FF4F8B`). An option without value (`bold`, `center`) is written alone. `width` and `max-width` only size the element: `center` is what centers it.
Existing stylesheets: `class "x"` replaces the default look, `look "x"` adds a class and keeps it (prefer named styles, below). `markdown text` renders Markdown; its code blocks (```kaury, ```bash, ```js) are colored at build time.
Screens: `mobile …` (up to 640), `tablet …` (641 to 1024, phones not included: what must also change on a phone gets its own `mobile` line), `desktop …` (options for that size; with a block below = content shown only there). A `size` above 36 shrinks by itself on small screens; a size written on a screen line is exact (`mobile size 46`). A screen line is written under the element it changes, or in a named style:
```kaury
page "/"
  grid columns 2 1, gap 32
    tablet columns 1, gap 24      // a grid does not fold by itself: say it
    mobile columns 1
    text "Left"
    text "Right"
```
Images and speed (the build does it, nothing to write): every picture of `public/` is made in WebP at several widths, with its real size (no layout jump); the first image of a page loads at once, the others when they come near; a picture written as a background (`background "hall.jpg"`) is served the same way, and announced to the browser when it opens the page. What is yours to write: the `width` of a small image (`width 210`: it is then fetched at that size), a description for every image, and no `immediate` on a scene unless the 3D must start before the visitor's first gesture (it costs the score on phones).
Contrast: a color written for a text is checked against the background of the box that contains it (4.5 for a small text, 3 from size 24); the warning gives a shade that works. A big pale text that is only decoration says so: `attr "aria-hidden" "true"`.

**Your own styles and animations** (never write CSS: everything has a Kaury form):
```kaury
style card-dark                       // a new word: use it on any element line → box card-dark
  background #1C1A1A, padding 24, radius 24, shadow hard
  hover lift 4                         // states the browser knows: hover, focus, pressed, disabled, checked
  selected background orange           // states you give with a condition on the element line: selected, current, open → box card-dark, selected (tab == 1)
  link color orange                    // parts inside: title, subtitle, text, link, image, button, icon, code, block, list, item, table, cell, quote, summary, emphasis, logo, field, label
  mobile padding 12                    // screens: mobile, tablet, desktop

style wide
  max-width 900, center

style button                           // the name of an element restyles all of them (button, title, header, footer, markdown, logo, emphasis…)
  border 2 black, radius 999

animation slide, 30s, loop, linear     // options: duration, loop, times n, delay 1s, linear | smooth | bounce, steps n, alternate, scroll (plays while scrolling)
  from move 0 0                        // steps: from, to, or a percentage (50%), with style options: move x y, grow, tilt, opacity, reveal 0%…100%, colors…
  to move -50% 0

state tab = 0
page "/"
  box card-dark, wide                  // several named styles on one line
    row no-wrap, slide                 // a named animation plays on the element
      text "Fresh every morning"
    box card-dark (tab == 1)           // a named style under a condition
      text "Second tab"
```
Text: `"An *immersive* site"` → emphasis; `"\n"` → a new line. States from a condition: `selected (tab == 1)`, `current (route.path == "/docs")`, `hidden (tab != 1)`, `open`; for any other look that depends on a condition, name a style and give it the same way (`style right`, then `button o, right (answered and o == q.answer)`). Tabs and filters are a state, buttons that set it and `selected`: `button "Pasta", selected (tab == "pasta") -> tab = "pasta"`. Layout: `grid columns 2 1` (unequal), `gap 24 56`, `pin bottom 0 right 20` (over its parent; `front` on the same line brings it in front of the rest), `middle` (in the middle of its row or grid line: a text next to a tall photo), `margin 0 0 0 auto` (pushed to the right of its row), `margin auto 0 0 0` (pushed to the bottom of its column: the button of a card), `sticky 96`, `border-top 2 black`, `clip`, `no-wrap`, `plain` (no underline), `grain` (paper texture; on the site style: the whole page). Site style: `radius 24, max-width 1400` set the radius and the width of the whole site. Elements: `details "Question?"` (opens on click, content below), `embed "url", "title"` (another page inside), `logo "mark.svg" "Name"`.

**Interactions**: `-> action` on the line (click; submit for a form; input for a field), or a child line `on click -> …`, `on hover -> …`, `on load -> …`, `on scroll -> …`. An action is one line or an indented block after `->`. `open menu` / `close menu` / `toggle menu` set a true/false state. `go "/page"` changes page.

**Conditions and loops in a page**: `if`, `else if`, `else`, `for … in …` produce UI and update by themselves. A condition is a line of its own, with the element indented below — never an option of the element.

**Data**: `products = await load "/api/products"` in a page does not block the display; the list fills in when the data arrives.

**Content in files** (a blog, a list of products, the texts of the site): Markdown and YAML files next to the site, read at build time. Adding an entry is adding a file: nothing to change in the code. The fields are those written in the files (`title`, `date`… at the top of a Markdown file, between two `---` lines); a field read in the code that no file has gets a warning with the one meant.
```kaury
import posts from "./content/posts/*.md"     // a list: one entry per file (its front matter, plus slug, body, created, updated)
import about from "./content/about.yaml"      // one object

page "/blog"
  section
    title "Blog of {about.name}"
    for post in posts.sort(p -> p.date).reverse()
      card post.title
        text post.description
        link "Read" "/blog/{post.slug}"

page "/blog/{post.slug}" for post in posts    // one page per entry
  seo post.title, post.description
  section
    title post.title
    markdown post.body
```

**Components**:
```kaury
component Card name image
  card
    image image, name, radius 16
    text name, bold
  style shadow soft, hover lift 4

page "/"
  Card "Strawberry" "strawberry.png"
```
Name starts with a capital letter. Parameters in order, without parentheses and without names: `Card p.name, p.photo`. What is indented under a call goes where `slot` is.

**Form**:
```kaury
state sent = false
page "/"
  form -> sent = true
    field email "Your email", type email, required, label "Email"
    select size "S", "M", "L", label "Size"
    checkbox agree "I agree to the terms"
    button "Send"
  if sent
    text "Thanks {email}, size {size}!"
```
The first word of a field is the state it fills (`email`, `size`, `agree`), created when it does not exist.

**Form sent by e-mail**: `form mail "hello@bloom.ch"` sends every field to that address, then runs the `->` action (`subject "New order"` optional). `kaury dev` shows the e-mail in the terminal; to really send, set `KAURY_MAIL_KEY` (a free resend.com key) on the host or in `.env`. `kaury build` writes the endpoint for Netlify, Vercel, Cloudflare Pages and PHP hosts (`dist/api/kaury-mail.php`; on an FTP host the key goes in `kaury-mail-key.txt` next to the site's folder). The address never appears in the page.
```kaury
state sent = false
page "/"
  form mail "hello@bloom.ch", subject "New request" -> sent = true
    field name "Your name", required, label "Name"
    field email "you@example.com", type email, required, label "Email"
    textarea message "Your message", required, label "Message"
    button "Send"
```

**Ready-made blocks** (nothing to import; a component of the same name written in the site replaces one). Prefer them for usual sections. A block with a heading is the section named after it (`Pricing plans, "Prices"` → `#prices`, found by `links Prices`); `Contact` is `#contact`, the default target of buttons.

| Block | Values | Items |
|---|---|---|
| `Hero` | heading, intro, action, href, picture | |
| `Features` | items, heading | `{ icon, title, text }` |
| `Steps` | items, heading | `{ title, text }` (numbered) |
| `Stats` | items | `{ value, label }` |
| `Table` | rows, columns, heading | rows: your list as it is; columns: `{ label, field, format, align }` (`format`: `"price"`, `"date"` or `"number"`; `align: "right"` for figures). A real `<table>`; a click on a column sorts by it, a second click the other way |
| `Chart` | items, heading, unit, scale | `{ label, value }`: bars, the tallest one fills the height; `unit` is written after each figure (`" CHF"`, `" %"`); `scale` is the value of a full bar, to give when two lists must be compared (a switch between two years) |
| `Pricing` | plans, heading | `{ name, price, per, text, features: [..], button, link, featured: true }` |
| `Testimonials` | items, heading | `{ quote, name, role, photo }` |
| `Team` | people, heading | `{ name, role, photo }` |
| `Logos` | images, heading | image files |
| `Gallery` | images, heading | image files |
| `Faq` | items, heading | `{ q, a }` |
| `Cta` | heading, intro, action, href | |
| `Contact` | to, heading, intro, thanks | form sent by e-mail to `to` |
| `Footer` | name, note | |

```kaury
let plans = [{ name: "Solo", price: "9 CHF", per: "/ month", features: ["1 site"], featured: true }]
page "/"
  Hero "Flowers that *speak*.", "Delivered the same day.", "Order", "#prices"
  Pricing plans, "Prices"
  Contact "hello@bloom.ch"
  Footer "Bloom"
```
A block is written at the level of the sections (it is one), not inside a `section`. Its last values can be left out; a value in the middle that you do not want is `""` (`Chart months, "", " CHF"`).
Figures: a table and a chart are blocks too, fed by the lists you already have (a `let` made from a state with `.filter` gives a table or a chart that follows that state: a switch between two years is one `state`).
```kaury
let gifts = [{ date: "2026-10-10", donor: "Claire D.", amount: 120 }, { date: "2026-10-08", donor: "Anonymous", amount: 50 }]
let months = [{ label: "Jan", value: 1850 }, { label: "Feb", value: 1420 }, { label: "Mar", value: 2360 }]
page "/"
  Chart months, "Donations per month", " CHF"
  Table gifts, [{ label: "Date", field: "date", format: "date" }, { label: "Donor", field: "donor" }, { label: "Amount", field: "amount", format: "price", align: "right" }], "Latest donations"
```

**Theme colors** (follow the site): `accent` (first site color), `on-accent` (text on it), `ink` (text), `muted` (soft text), `line` (borders). Fonts: `font "text"` and `font "titles"` are the two fonts of the site, the first and the second name of its `fonts` line; `font "mono"` is the one of code. Titles take the second by themselves.

## 4. Immersion

Levels: a **touch** (one `object` alone in a page), a **scene** (`scene` with decor, light, camera), a **universe** (the whole site). An object can be 2D (`.png .jpg .webp .svg`), animated 2D (`.json` Lottie), 3D (`.glb .gltf`, Meshopt/Draco compressed accepted) or a built-in shape, with no file: `object "knot", color pink, metal` (`sphere`, `cube`, `torus`, `knot`, `cone`, `cylinder`, `capsule`, `gem`, `pyramid`; materials `metal`, `matte`, `glass`, `glow`). The code is the same.

```kaury
page "/"
  scene home, fullscreen, particles bubbles          // particles stars|snow|bubbles|dust|confetti
    light studio                                      // studio|soft|sunset|night|neon|day|dramatic
    camera follows mouse                              // fixed|follows mouse|fly|free|orbit
    object can "crush.glb", size 1.2, position 2 0 0, alt "A can of Crush", fallback "can.png"
      spin on scroll                                  // also: spin, spin 90/s, spin slow, spin x
      follows mouse, smooth
      on click -> jump
    character mascot "mascot.glb", alt "The mascot"   // object with named animations
      enters from right                               // left|right|top|bottom|fade|zoom
      says "Hi!"
      on click -> play "dance"
    title "Taste the difference"                      // the content of a scene goes in front of the 3D
```

Motions (child line = permanent; after `->` = once): `spin`, `float`, `jump`, `pulse`, `sway`, `follows mouse`, `enters from …`, `parallax 0.3`, `says "text"`, `play "animation"`. Modifiers: `smooth`, `slow`, `fast`, `reverse`. Target a named object: `-> jump can`.
Where things are: the content of a scene is laid out like that of a section, in front of the 3D; an object stands in the middle unless `position` moves it. On a wide screen, x from about -3.5 to 3.5 and y from -2 to 2 are in view (`position 2 0 0`: to the right of a text on the left); on a phone an object on the side comes back toward the middle by itself.
Object options: `size`, `position x y z`, `rotation x y z`, `height` (single object), `fallback "image.png"` (when the device cannot do 3D), `shadows`, `alt "description"` (accessibility and Google), `animation "name"` (character), `immediate`. Scene options: `height`, `background`, `fog`, `ground`, `particles`, `immediate`.
Sound: `sound "ambient.mp3", loop, volume 0.4` (a mute button appears by itself); as an action: `-> sound "click.mp3"`.

Automatic rules: the 3D loads only on pages that contain it, when it becomes visible, after the page is displayed and the visitor's first gesture (add `immediate` to skip the wait); until then a built-in shape shows its silhouette, drawn by the page in its color, at its size and at its place, and a model file shows its `fallback` picture (give one: it is also what a device without 3D shows); the HTML content exists before the 3D; reduced motion is respected; on a narrow screen the camera steps back.

## 5. Golden rules for correct Kaury

1. A UI element always **starts a line**; its options are separated by **commas**: `title "Hello", size 80, pink`.
2. For a value to change on screen, declare it with `state` (or let an assignment `x = …` in the page create it).
3. Files (images, `.glb`, sounds) go in `public/` and are written without `/`: `"photo.jpg"`.
4. `==` compares, `=` stores. A `let` is never assigned again; when what it is made from reads a state, it follows that state.
5. Inside a UI line, a function is called **with parentheses**: `text total-price(cart)`, `text now()`.
6. The first item of a content element is its content: `text size` shows the variable `size`; options come after a comma (`text size, bold`).
7. The first word of a field is the state it fills: `select size "S", "M", "L"` creates the state `size`.
8. An empty value shows nothing; before calling something on it, test it: `if user` then, below, `text user.name.upper()`.

## 6. Complete example

```kaury
site "Flowers"
  colors accent #E93D82, cream #FFF6EE
  font "Satoshi"
  lang "en"

state cart = []
let total = sum cart, b -> b.price
let bouquets = [
  { name: "Peonies", price: 45, image: "peonies.jpg" },
  { name: "Tulips", price: 30, image: "tulips.jpg" }
]

component Bouquet b
  card b.name, b.image
    text price(b.price), bold
    button "Add" -> cart.add b
  style hover lift 6, shadow soft

page "/"
  seo "Flowers", "Bouquets delivered in Vevey"
  style background cream
  section header
    logo "Flowers"
    links Bouquets, Contact
  scene fullscreen, particles dust
    light soft
    object "knot", size 1.4, color accent, metal
      spin slow
      follows mouse, smooth
    title "Flowers that speak", size 72
  section bouquets
    grid 3 columns, gap 24
      for b in bouquets
        Bouquet b
    text "Cart: {cart.length} bouquet(s), {price(total)}"
```

## 7. Coming from HTML, CSS and JavaScript

What you already know has a Kaury form. The compiler gives it too when you write the other one by habit.

| HTML | Kaury |
|---|---|
| `<div>` | `box` — or `section`, `row` (side by side), `column` (stacked), `grid 3 columns` |
| `<h1>`, `<h2>`, `<h3>` | `title "…"` (the first of the page is the `<h1>`, the next ones `<h2>`), `subtitle "…"`, `subtitle "…", level 3` |
| `<p>`, `<span>` | `text "…"` |
| `<a href="/contact">Contact</a>` | `link "Contact" "/contact"` |
| `<img src="photo.jpg" alt="…">` | `image "photo.jpg", "What it shows"` |
| `<ul><li>` | `list`, with `item "…"` lines below |
| `<table>` | the block `Table rows, columns` (sortable); a chart: `Chart items` |
| `<input>`, `<textarea>`, `<select>` | `field email "Your email"`, `textarea message "…"`, `select size "S", "M", "L"` |
| `<button onclick="…">` | `button "Go" -> count += 1` |
| `<hr>`, `<br>`, `<iframe>` | `divider`, `"\n"` inside a text, `embed "https://…", "What it is"` |
| `class="card"` | a named style: `style card` once, then `box card` |

| CSS | Kaury |
|---|---|
| `font-size: 20px` | `size 20` |
| `font-weight: 600` | `weight 600`, or `bold` |
| `color`, `background-color` | `color pink`, `background pink` |
| `border-radius: 12px` | `radius 12` (`round` = fully round) |
| `border: 1px solid gray` | `border 1 gray` |
| `box-shadow` | `shadow soft` (`medium`, `strong`, `hard`) |
| `margin-top: 20px` | `margin 20 0 0 0` (top, right, bottom, left) |
| `padding: 12px 24px` | `padding 12 24` |
| `display: flex` | the elements `row` and `column` |
| `display: grid` | `grid 3 columns, gap 24` |
| `display: none` | `hidden`, or `hidden (count == 0)` |
| `text-align: center` | `align center` (the text), `center` (the content) |
| `position: sticky`, `z-index` | `sticky`, `front` |
| `overflow: hidden` | `clip` |
| `:hover { … }` | `hover lift 4, shadow strong` |
| `@media (max-width: …)` | `mobile padding 12`, `tablet 2 columns` |
| `transition` | nothing: changes are animated by themselves |
| `@keyframes` | `animation name` with `from` and `to` lines |

| JavaScript | Kaury |
|---|---|
| `const x = 3` / `let x = 3` | `let x = 3` (fixed) / `state x = 3` (changes on screen) |
| `useState(0)` | `state count = 0`, then `count += 1` |
| `===`, `!==` | `==`, `!=` |
| `&&`, `\|\|`, `!x` | `and`, `or`, `not x` |
| `x => x * 2` | `x -> x * 2` |
| `` `Hello ${name}` `` | `"Hello {name}"` |
| `a ? b : c` | `if a then b else c` |
| `function add(a, b) { return a + b }` | `function add a b then a + b` |
| `null`, `undefined` | `none` |
| `list.push(x)`, `list.includes(x)` | `list.add x`, `x in list` |
| `console.log(x)` | `print x` |
| `if (x) { … } else if (y) { … }` | `if x`, `else if y`, each with its block indented below |
| `for (const p of products)` | `for p in products` |
| `;` and `{ }` | nothing: one instruction per line, blocks by indentation |

## 8. The French words

For a file asked in French. Each English word and its French ones; accents are optional (`état` = `etat`), and the two languages can be mixed in one file. A word that is not here has no French form: write the English one.

**Keywords, elements and values**: let = soit · state = etat · function = fonction · then = puis / alors · if = si · else = sinon · for = pour · in = dans · while = tant · await = attends · try = essaie · catch = erreur · import = importe · from = de / depuis · as = comme · export = exporte · return = retourne · break = arrete · true = vrai · false = faux · none = rien / aucun · and = et · or = ou · not = non · open = ouvre · close = ferme · toggle = bascule · go = aller · component = composant · header = entete / en-tete · footer = pied / pied-de-page · grid = grille · column = colonne · row = ligne / rangee · box = boite · card = carte · title = titre · subtitle = sous-titre · text = texte · link = lien · links = liens / menu · button = bouton · form = formulaire · field = champ · textarea = zone / zone-texte / zone-de-texte · select = choix / liste-deroulante · checkbox = case / case-a-cocher · list = liste · item = element · icon = icone · divider = separateur · spacer = espaceur · details = deplie · embed = integre · slot = contenu · tablet = tablette · desktop = ordinateur · colors = couleurs · font = police · fonts = polices · lang = langue · url = adresse · alternate = traduction · head = tete · wrapper = enveloppe · object = objet · character = personnage · light = lumiere · on = au · click = clic · hover = survol · scroll = defilement · load = chargement · follows = suit / follow · mouse = souris · enters = entre / enter · spin = tourne / turn · float = flotte · jump = saute · sway = balance · says = dit / say · play = joue · sound = son / audio · parallax = parallaxe · smooth = doux / douce · slow = lent / lente · fast = rapide · reverse = inverse · left = gauche · right = droite · top = haut · bottom = bas · fade = fondu · loop = boucle · once = fois / une-fois · sunset = coucher-de-soleil · night = nuit · day = jour · dramatic = dramatique · fixed = fixe · fly = vol · free = libre · orbit = orbite · slide = glisse · curtain = rideau · stars = etoiles · snow = neige · bubbles = bulles · dust = poussiere · confetti = confettis · medium = moyenne / moyen · strong = forte / fort · hard = dure / dur · inner = interieure · center = centre · justify = justifie · pointer = main / pointeur · arrow = fleche · number = nombre · password = motdepasse · tel = telephone · search = recherche

**Options**: background = fond · color = couleur · font = police · size = taille · bold = gras · light = leger / fin · weight = poids / graisse / epaisseur · italic = italique · upright = droit / no-italic · underline = souligne · plain = simple · uppercase = majuscules · line-height = interligne · tracking = lettres / interlettrage · align = aligne · center = centre · middle = milieu · radius = coins / rayon / arrondi · round = rond / pill · shadow = ombre · glow = lueur / neon · text-glow = lueur-texte · stroke = contour · mesh = maillage · border = bordure · border-top = bordure-haut · border-bottom = bordure-bas · pin = epingle · clip = coupe · no-wrap = sans-retour · margin = marge · padding = remplissage / interieur · gap = espace · width = largeur · height = hauteur · max-width = max-largeur / largeur-max · min-height = min-hauteur / hauteur-min · fullscreen = plein-ecran / full · full-width = pleine-largeur · zoom = echelle · opacity = opacite · blur = flou · grayscale = noir-et-blanc / monochrome / greyscale · shade = voile / scrim / overlay · glass = verre · gradient = degrade · text-gradient = texte-degrade · columns = colonnes / colonne / cols / column · hidden = cache / hide · sticky = colle · front = devant · cursor = curseur · hover = survol · lift = monte / leve / lever / souleve · grow = grossit · tilt = penche · move = deplace / translate · reveal = devoile · animate = anime · class = classe · look = allure · tag = balise · attr = attribut · selected = selectionne · current = courant · open = ouvert · level = niveau · alt = texte / description · cover = couvre · loop = boucle · muted = muet · autoplay = auto · controls = controles · to = vers / href · outline = contour · ghost = discret / subtle · large = grand · small = petit · disabled = desactive · mail = courriel / email · subject = sujet / objet · new-tab = nouvel · min = mini · max = maxi · step = pas · required = requis · label = etiquette · rows = lignes · fallback = secours · shadows = ombres · immediate = immediat · metal = metal · matte = mat · fog = brouillard · ground = sol / floor · particles = particules · animation = anime

---

# Getting started

URL: https://dev.kaury.studio/docs/getting-started/

Kaury needs **Node.js 18 or newer**. Nothing else: no framework, no bundler to configure, no config file.

## Install

```bash
npm install -g @kaury/cli
```

Check it worked:

```bash
kaury --version
```

## Create a project

```bash
kaury new my-site
cd my-site
kaury dev
```

Open `http://localhost:3000`. The whole site is in **`site.kaury`**: edit it, save, and the page reloads by itself.

Prefer a real site to start from? `kaury new my-site --template landing` (or `blog`, `portfolio`) makes one from [ready-made blocks](/docs/blocks/).

A new project looks like this:

```
my-site/
  site.kaury     ← pages, logic, style and 3D
  public/        ← images, 3D models (.glb), sounds, fonts
```

## Your first page

Replace the content of `site.kaury` with:

```kaury
state likes = 0

page "/"
  section fullscreen, center
    title "Hello, world", size 80
    button "I like it ({likes})", large -> likes += 1
```

Three ideas are already at work:

- `page "/"` is an address. One `page` = one URL.
- `state likes = 0` is a **reactive** value: when it changes, everything that reads it updates.
- `-> likes += 1` is the action of the button. No event listener, no `useState`, no selector.

## Build the final site

```bash
kaury build
```

The optimized site lands in `dist/`: one HTML file per page, rendered on the server, with its CSS inlined, images converted to responsive WebP, fonts self-hosted, `sitemap.xml`, `robots.txt` and `llms.txt` generated.

It is a **static site**: it works on any host (Netlify, Vercel, Cloudflare Pages, GitHub Pages, an Apache or Nginx server…).

A site that lives in a folder of another site (`user.github.io/project/`, `example.com/demo/`) is built with its folder: `kaury build --base /project/`. Every address of the site then starts there, pictures, pages and scripts alike.

## Put it online

```bash
kaury deploy --netlify   # or --vercel
```

Or drag the `dist/` folder onto [app.netlify.com/drop](https://app.netlify.com/drop).

## All the commands

| Command | What it does |
|---|---|
| `kaury new my-site` | creates a ready-to-use project |
| `kaury dev` | shows the site and reloads it on every change |
| `kaury build [--out dist] [--base /folder/]` | makes the final, optimized site in `dist/` (`--base`: for a site served from a folder) |
| `kaury check [--json]` | checks the code and renders every page, without building (`--json` for AI assistants and editors) |
| `kaury run program.kaury` | runs a program without pages |
| `kaury compile site.kaury` | shows the generated JavaScript |
| `kaury deploy --netlify` | builds then publishes |

Error messages follow the language of your system; force it with `--lang en` or `--lang fr`.

## Editor

The **VS Code extension** (in `editors/vscode/` of the repository) adds coloring, completion of every element and option, and errors underlined as you type.

## Next

- [Build a real site in 10 steps](/docs/tutorial/)
- [Try Kaury in the browser](/playground/), nothing to install
- [Give Kaury to your AI assistant](/for-ai/)

---

# Tutorial — a real site in 10 steps

URL: https://dev.kaury.studio/docs/tutorial/

We build **Bloom**, a fictional flower shop: a home page with a 3D hero, a list of bouquets, a cart that survives a reload, and a contact page. Every step adds a few lines to the same `site.kaury`.

## 1. The site

```kaury
site "Bloom"
  colors accent #E93D82, cream #FFF6EE
  font "Satoshi"
  lang "en"
  url "https://bloom.example"
```

`colors` gives names to colors, usable everywhere (`background cream`). The font is downloaded at build time and served by your site: no request to Google.

## 2. A page

```kaury
page "/"
  seo "Bloom — flowers in Vevey", "Fresh bouquets, delivered the same day."
  style background cream
  section fullscreen, center
    title "Flowers that speak", size 80
    text "Fresh bouquets, delivered the same day."
```

`seo` writes the `<title>`, the description, Open Graph and the canonical link.

## 3. A header

```kaury
  section header, sticky, glass
    logo "Bloom"
    links Bouquets, Contact
```

`links` builds a menu. `Bouquets` points to `#bouquets` if a section has that name, otherwise to the page `/bouquets`. On phones, the menu folds behind a button by itself.

## 4. Data

```kaury
let bouquets = [
  { name: "Peonies", price: 45, image: "peonies.jpg" },
  { name: "Tulips", price: 30, image: "tulips.jpg" },
  { name: "Wild", price: 38, image: "wild.jpg" }
]
```

Images go in `public/` and are written without `/`.

## 5. A loop and a component

```kaury
component Bouquet b
  card b.name, b.image
    text price(b.price), bold
  style hover lift 6, shadow soft

page "/"
  section bouquets
    subtitle "Our bouquets"
    grid 3 columns, gap 24
      for b in bouquets
        Bouquet b
```

A component name starts with a capital letter. `price 45` gives `CHF 45.00` (or `price 45, "EUR"`).

## 6. State: a cart

```kaury
state cart = []
let total = sum cart, b -> b.price
persist "cart", cart
```

`total` reads a state, so it recomputes itself. `persist` keeps the cart in the browser across reloads. In the component, add:

```kaury
    button "Add" -> cart.add b
```

And anywhere in the page:

```kaury
    text "Cart: {cart.length} bouquet(s), {price(total)}"
```

## 7. Conditions

```kaury
    if cart.length == 0
      text "Your cart is empty."
    else
      button "Order ({price(total)})", large -> ordered = true
    if ordered
      text "Thank you!", bold, pink
```

`ordered = true` creates the state on the fly.

## 8. The 3D hero

Put a `flower.glb` in `public/`, then replace the first section:

```kaury
  scene fullscreen, particles dust
    light soft
    object "flower.glb", size 1.4, alt "A peony"
      spin slow
      follows mouse, smooth
    title "Flowers that speak", size 80
```

That's it. Three.js loads **only on this page**, after the page is displayed and the visitor's first gesture, so Lighthouse stays at 100.

## 9. A second page and a form

```kaury
page "/contact"
  seo "Contact", "Order a bouquet or ask a question."
  section
    title "Contact"
    form -> sent = true
      field email "Your email", type email, required, label "Email"
      textarea message "Your message", label "Message"
      button "Send"
    if sent
      text "Thanks, we answer within the day."
```

## 10. Build and publish

```bash
kaury build
kaury deploy --netlify
```

You now have a multi-page site with server rendering, a 3D hero, a persistent cart, a form, a sitemap, `llms.txt` and structured data — in about 70 lines.

**Next:** [the language in depth](/docs/language/) · [every element](/reference/)

---

# The language

URL: https://dev.kaury.studio/docs/language/

Kaury is a complete language, not a template syntax: it has variables, functions, loops, errors, modules, and it can run programs without any page (`kaury run`). It compiles to plain JavaScript.

## Blocks and comments

A block is a line followed by lines indented by **2 spaces**. No braces, no semicolons.

```kaury
// a comment
if score > 10
  print "well done"
```

## Values

```kaury
let tax = 8.1                 // a fixed value: never changes
state count = 0               // a reactive state: the page follows it
let total = price * quantity  // reads a state → recomputed by itself
delivery = 7                  // assignment (creates the variable if needed)
count += 1
```

Texts are always between double quotes, with `{…}` interpolation:

```kaury
let name = "Ada"
print "Hello {name}, you have {count * 2} points"
```

Numbers can carry a unit: `24px`, `2s`, `300ms`, `50%`, `100vh`, `90deg`, `20/s`. Other values: `true`, `false`, `none`, lists `[1, 2]`, objects `{ name: "Tulip", price: 30 }`, ranges `1..5`.

Names may contain hyphens: `total-price`. Write subtraction with spaces: `a - b`.

## Functions

```kaury
function double x then x * 2        // one line

function total-price cart           // a block: the last line is the result
  sum cart, a -> a.price * a.quantity
```

Call with or without parentheses: `double(4)`, `print total`, `sum cart, a -> a.price`.
Anonymous functions: `x -> x * 2`, `(a, b) -> a + b`, `-> count += 1`.

## Conditions

```kaury
if total > 50
  delivery = 0
else if total > 20
  delivery = 4
else
  delivery = 7

let label = if age >= 18 then "adult" else "child"
```

Comparisons: `== != < > <= >=`. Logic: `and or not`. Membership: `x in list`.

## Loops

```kaury
for p in products
  print p.name
for p, i in products
  print "{i}: {p.name}"
for i in 1..10
  print i
while lives > 0
  lives -= 1
```

`break`, `continue` and `return value` work as expected.

## Lists, texts and objects

```kaury
let cheap = products.filter(p -> p.price < 20)
let names = products.map(p -> p.name).join(", ")
let sorted = products.sort(p -> p.price)
cart.add product
cart.remove product
```

Other methods: `.find`, `.contains`, `.count`, `.unique()`, `.take n`, `.sum fn`, `.upper()`, `.lower()`, `.replace a, b`, `.split sep`, `.trim()`, `.starts-with x`… Properties: `.length`, `.first`, `.last`, `.keys`, `.values`.

## Built-in functions

`print`, `load url`, `send url, data`, `sum`, `average`, `min`, `max`, `round x, 2`, `random 1, 6`, `pick list`, `shuffle`, `range a, b`, `now()`, `format-date d`, `price 12.5`, `every 2s, -> …`, `later 1s, -> …`, `persist "key", state`, `copy text`, `confetti()`, `vibrate`, `scroll-to "id"`, `share {…}`, `json-ld {…}`, `slug "Hello world"`, `await 2s`. See the [reference](/reference/#functions).

## Asynchronous code and errors

```kaury
try
  products = await load "/api/products"
catch e
  print e.message
```

In a page, `await load` never blocks the display: the list fills in when the data arrives.

## Modules

```kaury
import { Card } from "./card.kaury"       // a component of another file
import confetti from "canvas-confetti"   // any npm package
import "theme.css"                        // a stylesheet for every page
```

In `card.kaury`, `export` makes a component (or a function) usable by other files:

```kaury
export component Card name
  card name
```

## Raw JavaScript

When you really need it, a `js` block is copied as is:

```kaury
js
  console.log(navigator.userAgent)
```

## French keywords

Every keyword has a French alias, accents optional: `soit` (`let`), `état` (`state`), `si` (`if`), `pour` (`for`), `titre` (`title`)… Errors follow the language of your system.

## Errors that explain

```
site.kaury:4:10 — "conut" does not exist. Did you mean "count"?
  4 |   button "+1" -> conut += 1
               ^^^^^
```

Every error has the line, the underlined word and a fix. `kaury check --json` gives the same errors to editors and AI assistants.

Nothing passes in silence:

- **Habits from other languages get the Kaury form.** `font-size 20` answers `in Kaury: size 20`; `h1 "Title"` answers `in Kaury: title "…"`; `&&` answers `"&&" is written "and"`. The same goes for `div`, `onClick`, `=>`, `===`, `var`, `elif`, a `:` after an option, a forgotten comma.
- **Values are checked.** An option that takes a number refuses a word (`size large`), an option that takes a color refuses what is not one (`color FF0000`), a function called with too few or too many values says which ones it takes.
- **The pages are rendered.** `kaury check` and `kaury build` display every page: what only fails at that moment (calling something on an empty value) is reported at its `.kaury` line, and the build stops instead of publishing a page with a hole in it.

## Empty values

`none` is the empty value. Reading a property of an empty value gives nothing: `user.name` shows nothing while `user` is `none`, and the page fills in when the value arrives. Calling something on an empty value is a mistake, said with its line: test first.

```kaury
state user = none

page "/"
  title "Hello {user.name}"
  if user
    text user.name.upper()
  button "Log in" -> user = { name: "Ada" }
```

---

# Pages & elements

URL: https://dev.kaury.studio/docs/web/

## The site

```kaury
site "Crush"
  colors pink #FF4F8B, cream #FFF4E8
  fonts "Inter", "Clash Display"   // text, titles
  lang "en"
  url "https://crush.example"
  style background cream, color #222
  transition fade                  // fade | slide | zoom | curtain | none
  seo "Crush", "Canned mocktails", image "share.jpg"
```

Everything is optional. `url` enables canonical links, `sitemap.xml` and `llms.txt`.

## Pages

```kaury
page "/"
  title "Home"
page "/about"
  title "About"
page "/product/:id"                         // route.params.id
  title "Product {route.params.id}"
page "/blog/{post.slug}" for post in posts  // one page per item of a collection
  title post.title
page "/404"
  title "Not found"
```

## The UI line

Every element follows the same shape:

```text
element content, option, option value, …
  children, style, motions and events
```

```kaury
title "Hi {name}", size 64, pink
image "photo.jpg", "A can", radius 16
button "Buy", large -> cart.add can
grid 3 columns, gap 24
```

A color alone colors the text of text elements and the background of blocks. On a colored background, the text color is chosen for **WCAG contrast** automatically.

## Elements

| Element | Use |
|---|---|
| `section [name]`, `header`, `footer`, `nav` | parts of the page (`section flavors` → `#flavors`) |
| `box`, `column`, `row`, `grid` | layout |
| `title`, `subtitle`, `text`, `icon` | text. The first `title` of a page is its `<h1>`, the next ones are `<h2>` by themselves; `level 3` → `<h3>` |
| `image`, `video` | media (`cover`, `autoplay`, `loop`…) |
| `link`, `links`, `logo`, `button` | navigation and actions |
| `card` | a card with title, image, text |
| `form`, `field`, `textarea`, `select`, `checkbox` | forms bound to states |
| `list`, `item`, `divider`, `spacer` | lists and spacing |
| `markdown` | Markdown rendered as rich text, colored code included |

Every option of every element is in the [reference](/reference/).

## Style

Options go on the line, or in a `style` line below:

```kaury
card
  style background white, radius 20, shadow soft, hover lift 6
```

Useful ones: `size`, `bold`, `align center`, `radius`, `round`, `shadow soft|medium|strong`, `border 1 gray`, `padding`, `margin`, `gap`, `max-width`, `fullscreen`, `glass`, `gradient c1 c2 [angle]`, `text-gradient c1 c2`, `opacity`, `blur`, `sticky`, `hover …`, `animate fade`. Numbers without unit are pixels.

With photographs: `background "hall.jpg", shade 0.6` darkens a background picture so the text in front can be read (`shade 0.9 bottom` toward one side only); `grayscale` shows a picture in black and white, and `hover grayscale 0` gives its colors back; `middle` puts a text in the middle of the photograph beside it. `upright` takes the italic of an emphasis away.

The compiler reads what a visitor would not: a text whose color is too pale for the background of the box it is in gets a warning, with a shade next to it that works.

## Responsive

```kaury
grid 4 columns, gap 24
  tablet 2 columns
  mobile 1 columns
```

`mobile`, `tablet`, `desktop` take options for that size — or, with a block below, content shown only there. By default grids fold, titles shrink and menus collapse on small screens. `tablet` is from 641 to 1024 pixels and does not include phones. A size written for one screen is exact: `mobile size 46`.

## Interactions

```kaury
button "Add" -> cart.add product           // click
button "Menu" -> toggle menu
button "Shop", to "/shop"
box
  on hover -> hovered = true
  on click
    count += 1
    confetti()
```

`open menu`, `close menu`, `toggle menu` set a true/false state. `go "/page"` changes page.

## Conditions and loops in a page

```kaury
if cart.length == 0
  text "Empty for now."
else
  for item in cart
    row gap 12
      text item.name
      button "Remove", small -> cart.remove item
```

They produce UI and update by themselves.

## Components

```kaury
component Card name image
  card
    image image, radius 16
    text name, bold
    slot
  style shadow soft, hover lift 4

Card "Strawberry" "strawberry.png"
  text "Our bestseller"      // goes where slot is
```

## Forms

```kaury
form -> sent = true
  field email "Your email", type email, required, label "Email"
  select size "S", "M", "L", label "Size"
  checkbox agree "I agree to the terms"
  button "Send", disabled not agree
if sent
  text "Thanks {email}!"
```

Each field is bound to a state of the same name, created if missing.

## Your own styles

A design system without CSS. A `style` with a new name becomes a word you put on any element line:

```kaury
style card-dark
  background #1C1A1A, color white, padding 24, radius 24
  hover lift 4, shadow hard
  link color orange
  mobile padding 12

page "/"
  section
    box card-dark
      link "Read more" "/blog/"
```

- **states**: `hover`, `selected`, `current`, `open`, `focus`, `pressed`, `disabled`, `checked`;
- **parts** inside: `title`, `text`, `link`, `image`, `button`, `code`, `summary`, `emphasis`…;
- **screens**: `mobile`, `tablet`, `desktop`.

Named after an element, a style restyles all of them: `style button`, `style title`, `style header`, `style markdown`.

## Animations

```kaury
animation slide, 30s, loop, linear
  from move 0 0
  to move -50% 0

page "/"
  section
    row no-wrap, slide
      text "Kaury ✳ Kaury ✳ Kaury ✳"
```

Options: a duration, `loop`, `times 3`, `delay 1s`, `linear`, `smooth`, `bounce`, `steps 12`, `alternate`, and `scroll` to play it while the element scrolls into view. Steps are `from`, `to` or a percentage, with any style option (`move`, `grow`, `tilt`, `opacity`, `reveal 0%`…). Reduced motion is respected by itself.

## Exact HTML when you need it

Every element accepts `class`, `tag`, `attr`, `id` and `html`, to reuse an existing stylesheet or reach precise markup:

```kaury
box tag "figure", class "hero", attr "aria-label" "Our team"
text "Line one<br>line two", html
```

`head "…"` adds raw HTML to the `<head>` of a page, and a `css` block is still there for an existing stylesheet — but a Kaury site does not need one: [this site](https://github.com/theoblondel/kaury-lang/blob/main/site/site.kaury) has none.

---

# Blocks, forms and templates

URL: https://dev.kaury.studio/docs/blocks/

Most sites are made of the same sections: a first screen, features, prices, reviews, questions, a contact form. Kaury has them **ready-made**. Nothing to install or import: write the name, give the values.

```kaury
let plans = [
  { name: "Small", price: "29 CHF", features: ["7 stems", "A card"] },
  { name: "Large", price: "49 CHF", features: ["12 stems", "A card", "A vase"], featured: true }
]

page "/"
  section header
    logo "Bloom"
    links Prices, Contact
  Hero "Flowers that *speak*.", "Delivered the same day in Vevey.", "See the prices", "#prices"
  Pricing plans, "Prices"
  Contact "hello@bloom.ch"
  Footer "Bloom", "Flowers in Vevey since 2009"
```

They take the colors, fonts and radius of your site. A block with a heading is the section named after it: `Pricing plans, "Prices"` is `#prices`, so `links Prices` finds it.

## The blocks

| Block | Values, in order | Each item |
|---|---|---|
| `Hero` | heading, intro, action, href, picture | |
| `Features` | items, heading | `icon`, `title`, `text` |
| `Steps` | items, heading | `title`, `text` — numbered |
| `Stats` | items | `value`, `label` |
| `Table` | rows, columns, heading | columns: `label`, `field`, `format` (`"price"`, `"date"`, `"number"`), `align` — a real table, sorted by a click on a column |
| `Chart` | items, heading, unit, scale | `label`, `value` — bars; `unit` follows each figure; `scale` is the value of a full bar, to compare two lists |
| `Pricing` | plans, heading | `name`, `price`, `per`, `text`, `features`, `button`, `link`, `featured` |
| `Testimonials` | items, heading | `quote`, `name`, `role`, `photo` |
| `Team` | people, heading | `name`, `role`, `photo` (initial when no photo) |
| `Logos` | images, heading | image files |
| `Gallery` | images, heading | image files |
| `Faq` | items, heading | `q`, `a` |
| `Cta` | heading, intro, action, href | |
| `Contact` | to, heading, intro, thanks | |
| `Footer` | name, note | |

Only the first values are required; Kaury tells you when one is missing:

```
Error site.kaury, line 4: "Pricing" needs 1 value (plans), I see 0.
Try: Pricing plans, heading
```

The items are often in a YAML file, so the texts can change without touching the code:

```kaury
import home from "./content/home.yaml"

page "/"
  Features home.features, "Why Bloom"
  Faq home.faq
```

## Make a block yours

A block is an ordinary Kaury component. Write one with the same name and it replaces the built-in one:

```kaury
component Footer name
  footer
    text "{name} — handmade in Vevey"

page "/"
  Footer "Bloom"
```

To restyle without rewriting, use the theme colors: `accent`, `on-accent`, `ink`, `muted`, `line` follow your site, and `font "titles"` is your title font.

## Forms that send e-mails

Add `mail` and an address to a form: what is typed is sent there, then the `->` action runs.

```kaury
page "/"
  section contact
    form mail "hello@bloom.ch", subject "New request" -> sent = true
      field name "Your name", required, label "Name"
      field email "you@example.com", type email, required, label "Email"
      textarea message "Your message", required, label "Message"
      button "Send"
    if sent
      text "Thanks {name}, we answer within the day."
```

- **While you build**: `kaury dev` shows each e-mail in the terminal. Nothing leaves your computer.
- **To really send**: create a free key on [resend.com](https://resend.com) and set it as `KAURY_MAIL_KEY` on your host (or in a `.env` file to try locally).
- **Hosting**: `kaury build` writes the small function that sends the e-mail for Netlify, Vercel and Cloudflare Pages (keep the `netlify/`, `api/` and `functions/` folders it creates), and a PHP version in `dist/api/` for the hosts you fill by FTP (LWS, Infomaniak, OVH…).
- **On an FTP host**: copy `dist/` as usual, then put a file `kaury-mail-key.txt` holding the key **next to** the site's folder (on LWS: beside `htdocs/`), where the web never reaches it.
- **Safe by default**: the address is never in the page, the endpoint only writes to the addresses of your site, the answer goes to the visitor's e-mail (reply-to), and robots that fill the form instantly are ignored.

## Templates

`kaury new` starts from a template:

```bash
kaury new my-site                        # starter: teaches the language
kaury new my-shop --template landing     # hero, features, prices, reviews, questions, contact
kaury new my-notes --template blog       # Markdown posts, one page each
kaury new my-work --template portfolio   # gallery, process, clients, contact
```

Every template is a real site made of the blocks above, with its texts in `content/`, an `AGENTS.md` and the spec for AI assistants.

---

# Immersion — 3D, scenes, characters

URL: https://dev.kaury.studio/docs/immersion/

Immersion in Kaury has three levels, and the code is the same for all three:

- a **touch**: one `object` alone in a page;
- a **scene**: a `scene` with decor, light and camera;
- a **universe**: the whole site.

An object can be 2D (`.png .jpg .webp .svg`), animated 2D (`.json` Lottie) or 3D (`.glb .gltf`, Meshopt or Draco compressed). Files go in `public/`.

## A touch

```kaury
section hero, center
  title "Hello"
  object star "star.svg", size 0.6
    float
    follows mouse, smooth
    on click -> jump
```

## A scene

```kaury
scene home, fullscreen, particles bubbles
  light sunset
  camera follows mouse
  object can "can.glb", size 1.2, position 2 0 0, alt "A can of Crush"
    spin on scroll
    follows mouse, smooth
  title "Taste the difference"
```

Everything that is not 3D (titles, texts, buttons) goes **in front of** the 3D, as real HTML: readable by Google, by screen readers and by AI assistants.

| Option | Values |
|---|---|
| `light` | `studio`, `soft`, `sunset`, `night`, `neon`, `day`, `dramatic` |
| `camera` | `fixed`, `follows mouse`, `fly`, `free`, `orbit` |
| `particles` | `stars`, `snow`, `bubbles`, `dust`, `confetti` |
| scene options | `height`, `background`, `fog`, `ground`, `immediate` |
| object options | `size`, `position x y z`, `rotation x y z`, `fallback "image.png"`, `shadows`, `alt`, `immediate` |

## Motions

A motion on a child line is permanent; after `->` it plays once.

```kaury
object gem "gem.glb"
  spin 90/s            // also: spin, spin slow, spin x, spin on scroll
  float
  enters from right    // left | right | top | bottom | fade | zoom
  on click -> jump
```

Motions: `spin`, `float`, `jump`, `pulse`, `sway`, `follows mouse`, `enters from …`, `parallax 0.3`, `says "text"`, `play "animation"`. Modifiers: `smooth`, `slow`, `fast`, `reverse`. Target a named object from anywhere: `-> jump gem`.

`enters from …` also works on any HTML element: titles and cards appear as you scroll.

## Characters

A `character` is an object with named animations (from your `.glb`):

```kaury
character mascot "mascot.glb", animation "idle"
  enters from right
  says "Hi! Click me."
  on click -> play "dance"
```

## Sound

```kaury
sound "ambient.mp3", loop, volume 0.4   // a mute button appears by itself
button "Pop" -> sound "pop.mp3"
```

## Why it stays fast

The rules are automatic, you write nothing for them:

1. The 3D library (Three.js) is loaded **only on pages that contain 3D**.
2. It loads **when the scene becomes visible**, after the page is displayed and the visitor's **first gesture** (add `immediate` to skip the wait).
3. The HTML content exists before the 3D: the page is readable instantly.
4. `prefers-reduced-motion` is respected.
5. On narrow screens the camera steps back.
6. If the device cannot do 3D, `fallback "image.png"` is shown.

Result: the example site [Crush](https://github.com/theoblondel/kaury-lang/tree/main/examples/crush), with an animated 3D character, scores **100 / 100 / 100 / 100** on Lighthouse, on mobile and desktop.

---

# Content — collections, blog, Markdown

URL: https://dev.kaury.studio/docs/content/

Content lives in files next to your site, not in a database. Kaury reads it **at build time**: the pages are complete HTML, and the data is never shipped in the JavaScript.

## Import content

```kaury
import posts from "./content/*/index.md"   // a list: one entry per file
import about from "./content/about.yaml"    // one object
```

Supported: Markdown (`.md`, `.mdx`, `.markdown`), YAML (`.yaml`, `.yml`).

Each entry has the fields of its front matter, plus:

| Field | Value |
|---|---|
| `slug` | the name of the file (or of its folder for `index.md`) |
| `body` | the Markdown text |
| `created`, `updated` | ISO dates of the file |

Images written in the front matter (`cover: ./cover.jpg`) are copied, optimized and get their real dimensions.

## One page per item

```kaury
page "/blog/{post.slug}" for post in posts
  seo post.title, post.description
  section
    title post.title
    markdown post.body
```

## A list page

```kaury
page "/blog"
  section
    title "Blog"
    for post in posts.sort(p -> p.date).reverse()
      card post.title, post.cover
        text post.description
        link "Read", "/blog/{post.slug}"
```

## Markdown

`markdown text` renders Markdown as rich text:

- headings get an id and an anchor (`## Install` → `#install`);
- code blocks are **colored at build time** for `kaury`, `bash` and `js` — no highlighting library is sent to the browser;
- tables, lists, quotes and links work as expected.

## Pages with zero JavaScript

A page that has no state, no event and no 3D is sent **without any JavaScript**. Entrances (`enters from bottom`) are then done in pure CSS. Blog posts and docs pages are typically in this case: this page you are reading is one of them.

---

# SEO, GEO & performance

URL: https://dev.kaury.studio/docs/seo-geo/

A Kaury site is ready for search engines **and** for AI assistants (GEO, generative engine optimization) without a plugin.

## What every build generates

| File or tag | Purpose |
|---|---|
| server-rendered HTML for every page | content readable without JavaScript, by any crawler |
| `<title>`, description, canonical link | from `seo` and `url` |
| Open Graph and Twitter tags | sharing previews; share images cropped to 1200×630 |
| `sitemap.xml` | every page, collection pages included |
| `robots.txt` | open by default |
| `llms.txt` | an index of the site for AI assistants |
| JSON-LD `WebSite` | on the home page |
| `hreflang` alternates | with `alternate "fr" "/fr/"` |
| `.htaccess` and `_headers` | long cache for assets, on Apache and Netlify |

## Structured data in one line

`json-ld` turns any object into a `<script type="application/ld+json">`, given to `head`:

```kaury
let faq = {
  "@context": "https://schema.org",
  "@type": "FAQPage",
  mainEntity: [
    { "@type": "Question", name: "Do you deliver?", acceptedAnswer: { "@type": "Answer", text: "Yes, the same day." } }
  ]
}

page "/"
  head json-ld(faq)
```

## Writing for AI assistants

Assistants quote pages that answer a question plainly. Kaury helps on the technical side; the rest is writing:

- a **definition sentence** near the top ("Bloom is a flower shop in Vevey that…");
- headings phrased like the questions people ask;
- facts with numbers, dates and places;
- one page per topic, linked together.

## Why Lighthouse gives 100

- every page is rendered on the server, then the browser **adopts** that HTML (hydration) instead of rebuilding it;
- CSS is inlined: nothing blocks the first paint;
- images get real dimensions, responsive WebP versions and the right loading priority;
- fonts are downloaded at build time and served by the site;
- the 3D library loads only where needed, after the first gesture;
- text colors on colored backgrounds are chosen for WCAG contrast;
- a page without interaction ships zero JavaScript.

The measured numbers are on the [home page](/#performance).

---

# A design system without CSS

URL: https://dev.kaury.studio/blog/design-system-without-css/

The site you are reading is written in Kaury, and it has **no CSS file and no CSS block**. Its whole look — pills, cards, the ticker, the code that types itself — is made of three ideas.

## 1. Restyle an element everywhere

A style named after an element applies to all of them:

```kaury
style button
  border 2 black, radius 999, bold

style title
  font "Cabinet Grotesk", weight 800, tracking -1
```

## 2. Create your own words

Any other name makes a new word. Put it on any element line:

```kaury
style card-paper
  background #E9DDB9, radius 24, padding 32
  hover lift 4, shadow hard
  selected background black, color white
  link color orange
  mobile padding 20

page "/"
  section
    column card-paper
      subtitle "Simple to write"
      link "Read more" "/docs/"
```

Inside a style you can describe:

| Kind | Words |
|---|---|
| states | `hover`, `selected`, `current`, `open`, `focus`, `pressed`, `disabled`, `checked` |
| parts inside | `title`, `text`, `link`, `image`, `button`, `code`, `summary`, `emphasis`… |
| screens | `mobile`, `tablet`, `desktop` |

States follow your data: `button "Code", tab-pill, selected (tab == 0)`.

## 3. Animate with words

```kaury
animation scroll-left, 40s, loop, linear
  from move 0 0
  to move -50% 0

page "/"
  section
    row no-wrap, scroll-left
      text "Kaury ✳ Kaury ✳ Kaury ✳"
```

The code that types itself on the home page is the same idea with `steps 12` and `reveal 0%` → `reveal 100%`. An animation with `scroll` plays while the element scrolls into view. Visitors who ask their system for less motion get none, automatically.

## The result

One file, readable from top to bottom: colors, fonts, words, animations, then pages. Look at [the source of this site](https://github.com/theoblondel/kaury-lang/blob/main/site/site.kaury).

**Next:** [let an AI write your Kaury site](/blog/ai-writes-kaury/)

---

# Let an AI write your Kaury site

URL: https://dev.kaury.studio/blog/ai-writes-kaury/

Kaury was designed so that a language model can write it well: one way to do each thing, the same shape on every line, a whole site in a few dozen lines.

## The prompt

```text
Read https://dev.kaury.studio/kaury-ai.md — the full specification of the Kaury language.
Then write a complete Kaury site (one site.kaury file) for: a bakery in Lisbon,
with a 3D croissant, the menu, opening hours and a contact form.
```

`kaury-ai.md` is about 300 lines. It holds the syntax, the web elements, styles, animations, 3D and a list of golden rules. Assistants that browse can read the address; for the others, paste the file.

## The loop

1. Save the answer as `site.kaury`.
2. Run the checker:

```bash
kaury check --json
```

3. If there are errors, give the JSON back to the assistant. Each error has the line, the column, the word and the fix:

```json
{ "severity": "error", "file": "site.kaury", "line": 4, "column": 20, "message": "\"conut\" does not exist.", "fix": "did you mean \"count\"?" }
```

4. Repeat until `kaury check` is green, then `kaury dev`.

The checker also renders every page, so what only fails when a page is displayed is in the list too. And when the assistant writes HTML, CSS or JavaScript by habit, the fix is the Kaury form: `font-size 20` answers `in Kaury: size 20`, `&&` answers `"&&" is written "and"`.

An agent such as Claude Code or Cursor can run this loop on its own.

## Why it works better than JavaScript

- **Less to write, less to get wrong**: a full site is one answer, not twenty files.
- **No version soup**: there is no React 17 vs 19, no router to choose, no CSS framework to guess.
- **A strict compiler**: mistakes are caught before the browser, with a fix the model can apply.

**Start:** [read kaury-ai.md](/kaury-ai.md) · [see the files made for AIs](/for-ai/)

---

# Your first 3D scene, without a model

URL: https://dev.kaury.studio/blog/first-3d-scene/

You do not need a `.glb` file to start with 3D. Kaury knows nine shapes: `sphere`, `cube`, `torus`, `knot`, `cone`, `cylinder`, `capsule`, `gem` and `pyramid`.

## One object

```kaury
page "/"
  section center
    title "Hello, 3D"
    object "knot", color orange, metal, height 420
      spin slow
      follows mouse, smooth
```

An object alone in a page gets its own little scene. `metal` makes it shine; try `matte`, `glass` or `glow`.

## A full scene

```kaury
page "/"
  scene shapes, height 620, particles dust
    light studio
    camera follows mouse
    object knot "knot", color orange, metal, position -2.6 0 0
      spin slow
    object gem "gem", glass, position 0 0.9 -1
      float
    object ring "torus", color black, matte, position 2.6 0 0
      spin on scroll
      on click -> jump
    title "3D is a word."
```

- `light studio` lights the scene; there are also `soft`, `sunset`, `night`, `neon`, `day` and `dramatic`.
- `camera follows mouse` moves the camera gently with the pointer.
- The title is real HTML, **in front of** the 3D: Google and screen readers read it.

## Why it stays fast

Three.js is loaded only on pages that have 3D, when the scene becomes visible and after the visitor's first gesture. Until then, the page is plain HTML. That is how a site with 3D stays fast: the perfume example scores 96 on a phone and 100 on a desktop on Lighthouse.

When you have a real model, replace `"knot"` by `"chair.glb"`: the rest does not change.

**Next:** [a design system without CSS](/blog/design-system-without-css/)

---

# A landing page in 30 lines

URL: https://dev.kaury.studio/blog/landing-page-in-30-lines/

A landing page has always the same parts: a promise, three reasons to believe it, a price and a way to reach you. In Kaury each part is a few lines. Here is the whole page, then the details.

```kaury
site "Nimbus"
  colors accent #2F6BFF, ink #0E1525, cloud #F4F7FF
  fonts "Inter", "Clash Display"
  style background cloud, color ink

style plan
  background white, radius 20, padding 28, gap 12
  hover lift 6, shadow medium

page "/"
  seo "Nimbus — backups you forget about", "Automatic, encrypted backups for small teams."
  section hero, fullscreen, center
    title "Backups you *forget about*.", size 88
      enters from bottom
    text "Encrypted, automatic, restored in one click."
    button "Start free", large, to "#pricing"
  section features
    grid 3 columns, gap 24
      for f in ["Every hour", "End-to-end encrypted", "Restore in one click"]
        card f
          enters from bottom
  section pricing
    grid 2 columns, gap 24
      column plan
        subtitle "Solo", level 3
        title price(9), size 48
      column plan
        subtitle "Team", level 3
        title price(29), size 48
  section contact, center
    form -> sent = true
      field email "you@company.com", type email, required, label "Email"
      button "Get a demo"
    if sent
      text "Thanks, we write back today."
```

## What each part does

- `site` sets the colors and fonts once. The fonts are downloaded at build time and served by your site.
- `style plan` is a **named style**: a word you can put on any element. It has a hover state, no CSS needed.
- `title "Backups you *forget about*."` puts the words between stars in emphasis.
- `for f in [...]` makes one card per item. Add an item, a card appears.
- `form -> sent = true` runs when the form is valid; `sent` is created on the fly and the page shows the thank-you text by itself.

## Build it

```bash
kaury build
```

You get one HTML page rendered on the server, with its CSS inlined, a sitemap, `robots.txt` and `llms.txt`. Nothing to configure.

**Next:** [your first 3D scene](/blog/first-3d-scene/)