---
title: "Design CLI for agents"
description: "Use JSON responses and a review-before-apply loop to generate and refine a client design system."
requested_language: ar
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/ar/ai-agents/design-cli
version: unreleased (main)
docs_index: https://docs.systhema.app/ar/llms.txt
---
> This page isn't translated yet. Showing English.


Use `systhema design` when the agent needs to generate or edit the design system. It shares the design engine and export format with Systhema Design. See the [full CLI reference](https://docs.systhema.app/ar/design/systhema-design/cli.md) for commands and flags.

## Start from the supplied inputs

Identify the primary color, secondary colors, neutrals, heading and body fonts, logos and share image. Record missing assets or font substitutions. Do not turn every brand-book category into a color mode.

```bash
systhema design new --seed '#0E4DA4' --heading-font 'Space Grotesk' --body-font Inter --yes --json
systhema design status --json
systhema design diff --json
```

A design session stores its diff in `.systhema/design/design.json` and real assets in the adjacent `assets/` directory. It can exist before a scaffold. `--session <dir>` selects an explicit session if the project root changes.

## Parse success and failure

`--json` prints one JSON object. Only `ok` is guaranteed; other fields depend on the command:

```json title="Illustrative response shape"
{
  "ok": false,
  "error": "No design session found.",
  "hint": "Run systhema design init or check --session."
}
```

Read the exit status and `ok`. Report the provided recovery hint on failure. Do not treat the presence of `data` or a written export as proof that a later apply succeeded.

## Refine in dependency order

Seed palettes before customizing foundations that refer to them, then adjust typography and layout:

```bash
systhema design palette add accent '#E8590C' --json
systhema design color set foundations.decorative @accent.500 --json
systhema design color set foundations.bg '#FAF7F2' --json
systhema design type scale --base 18 --ratio majorThird --json
systhema design layout set section-padding 112 --bp lg --json
systhema design color check --json
```

A secondary chromatic color normally becomes a palette. A mode is a complete semantic re-skin. A near-black brand neutral normally reseeds `base` rather than adding another chromatic ramp.

## Review and apply

```bash
systhema design diff --json
systhema design apply --dry-run --json
```

Review planned writes with the task's approval requirements. Apply from a clean working tree when authorized:

```bash
systhema design apply --json
```

Apply writes tokens, config and configured assets, then runs sync. Re-read the generated project references afterward. Renaming a mode in a populated Payload site also requires migrating stored values; a design diff alone is not a database migration.

## Hand off or round-trip

```bash
systhema design export agent --out systhema.design.json --json
systhema design export figma --json
```

A later session can use `systhema design init --from systhema.design.json` when no session exists, or `systhema design import systhema.design.json` for an existing session. Browser and CLI exports can be imported back through the same formats.

Font catalog operations need network access. PNG-generating operations need the CLI's sharp installation. Other commands can continue when a raster dependency is unavailable.

Use the installed `systhema:design` skill and the [brand-book workflow](workflows.md) for the full sequence. Compose pages after applying the design; do not imitate the generated tokens with arbitrary JSX values.