Design CLI for agents

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 for commands and flags.

Start from the supplied inputsLink to this section

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.

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 failureLink to this section

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

{
  "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 orderLink to this section

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

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 applyLink to this section

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:

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-tripLink to this section

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 for the full sequence. Compose pages after applying the design; do not imitate the generated tokens with arbitrary JSX values.