---
title: "Files, Kalka folders and versions | Kalka docs"
description: "The file types Kalka saves, what a Kalka folder holds, how autosave and crash recovery work, and how to keep versions of a design with Git."
url: https://kalka.design/docs/files-versions
language: en
---

Your designs are files on your computer. Kalka never needs an account or a server to save them.

## Three ways to save a document

| Format | What it is | Good for |
| --- | --- | --- |
| Kalka folder | A folder of HTML pages, one stylesheet, design tokens and images | Working with developers and agents, keeping versions in Git |
| .kalka | The same folder packed into one file | Sending a design as a single file |
| .fig | Figma’s file format | Going back and forth with Figma |

**Save** (Cmd S on macOS, Ctrl S on Windows and Linux) writes to the file you opened. **Save As…** picks a new file, as `.fig` or `.kalka`. **Save As Folder…**, in the desktop app, asks for a name and a place and creates a new Kalka folder there.

Kalka refuses to save into a folder that already holds other files, such as a website project or Downloads, so it never mixes its files with yours. An empty folder or an existing Kalka folder is fine.

## What is in a Kalka folder

```
my-design/
  project.json          pages, artboard positions, settings, variables
  pages/
    home.html           one HTML file per page
    pricing.html
  styles.css            the classes your layers share
  design-system/
    tokens.json         your variables as W3C design tokens
    tokens.css          the same tokens as CSS custom properties
  assets/
    images/             every image, named by its content
  instructions/         optional rules, skills and documents for agents
```

_The Folder panel listing a Kalka folder: design-system, instructions, pages, project.json and styles.css_

The Folder panel shows the files Kalka writes for the document.
Each page is a plain HTML file you can open in a code editor or a browser. A developer can read it, review it in Git, and take what they need. The `instructions/` folder holds what you tell agents about this project: a summary, rules, your own skills and reference documents. See [Agents in Kalka](https://kalka.design/docs/agents).

## Saving safely

Kalka writes a new file beside the old one and swaps it in only once it is complete. A crash, a full disk or a failed write leaves your file as it was. A Kalka folder is saved the same way: every file is written aside first, so the folder is always either the last save or the new one, never a mix. A save cut short is finished the next time the folder opens.

## Autosave

Autosave is off for a new document. Turn it on with **Autosave** in the File menu: Kalka then saves a few seconds after you stop editing. It needs a file to write to, so save the document once first. Documents opened from a cloud storage workspace autosave on their own.

In Chrome and Edge, the browser asks for permission to write the file when you turn Autosave on. If an autosave fails, Kalka tells you once, and keeps your changes for crash recovery until a save works again.

## Crash recovery

While you work, Kalka keeps a copy of unsaved changes on your computer. If Kalka or your computer stops before you save, the next launch shows **Recover unsaved work**: **Restore** brings the documents back, linked to the files they came from, so the next save writes there. **Discard** drops them.

You can turn this off in Settings with **Automatically preserve unsaved work**.

## When another app changes your file

Git, a sync tool or another editor may change a file you have open. With no unsaved edits, Kalka reloads it. With unsaved edits, Kalka keeps them and tells you the file changed; choose **Reload from disk** to take the other version, or save to replace it with yours.

## Versions with Git

The **History** panel, in the left rail, keeps versions of a document with Git. It works in the desktop app, for a document saved on your computer, and uses the `git` already installed there.

- Open **History**. If the folder does not keep versions yet, click **Keep versions**. Kalka creates a Git repository in the document’s folder.

- Describe what changed under **What changed** and click **Record version**. Kalka saves the document first; if the save fails, nothing is recorded.

- To go back, click **Restore** next to a version. Kalka records where you were first, so restoring can itself be undone, then reloads the document.

For a Kalka folder, a version records the whole folder. For a `.fig` or `.kalka` file, it records that file only: other files beside it are never recorded or restored.

The first time, Kalka may ask for your name and e-mail. They are stored in that repository only.

### Publishing versions online

To keep your versions on GitHub or another Git host, create an empty repository there, paste its address under **Publish online** and click **Connect**. Kalka uses the Git sign-in already on your computer. After that, every version you record is published. **Get updates** brings in versions published from elsewhere, and **Publish** sends yours if you recorded some offline.

When an agent made the changes, the version says which one, such as Pebble.
