Ceramic Design System CLI

The same structured API powers terminal output, JSON automation, generated agent instructions, and the stdio MCP server.

npm install -D @utopia-studio-design/design-system-cli
npx utopia-ds init . --theme utopia-default --yes
npx utopia-ds room connect --id <room-id> --slug <room-slug> --name "Brand room" --brand "Brand" --source managed --client codex
npx utopia-ds search "Arabic data table" --json
npx utopia-ds component DataTable --json
npx utopia-ds registry --list --json
npx utopia-ds layout validate ./dashboard-layout.json --json
npx utopia-ds layout serialize ./dashboard-layout.json
npx utopia-ds logo-skill --list
npx utopia-ds logo-skill combinedmark --json
npx utopia-ds block interaction-workbench --copy ./src/interaction-workbench
npx utopia-ds template template-saas-solution-homepage --copy ./saas-website
npx utopia-ds template template-interaction-lab --copy ./interaction-lab
npx utopia-ds template template-dashboard-composer --copy ./dashboard-composer
npx utopia-ds template template-saas-solution-homepage --theme dextrum --copy ./dextrum-website
npx utopia-ds template validate ./my-community-template
npx utopia-ds template submit ./my-community-template
npx utopia-ds manifest --json
npx utopia-ds mcp

room connect writes a non-secret .ceramic/room.json manifest in the local workspace. The MCP server exposes it through get_room_context, so Codex, Claude Code, and Cursor can identify the exact Ceramic Brand Room while using the same component, theme, template, and documentation contracts. The initializer writes both Claude Code's project configuration (.mcp.json) and Cursor's project configuration (.cursor/mcp.json). Codex uses its own codex mcp add registration command shown by the Ceramic onboarding flow.

Logo Maker uses the same six-skill manifest in the browser and MCP. MCP clients can call list_logo_skills, get_logo_skill, then prepare_logo_maker_run. The prepared run includes Brand Room context, the selected skill prompt, reference ids, review policy, and the next approval-safe step. It also returns the shared Logo Quality Check gates from docs/design-system/logo-maker-methodology.md; it never implies that a draft was evaluated, approved, or published before artifact evidence exists.

theme create is a source-authoring operation rather than a consumer-project command. Run it from the root of the Ceramic Design System repository after installing the workspace dependencies:

npm install
npm run ds -- theme create your-theme-name

Replace your-theme-name with the lowercase kebab-case ID you want for the theme.

Programmatic consumers can import @utopia-studio-design/design-system-cli/api. The Ceramic Composition Registry and versioned Layout JSON are the source of truth for agent and Studio dashboard composition. The Dashboard Composer's optional Puck adapter consumes this API, but it does not define Ceramic blocks or styling.

To run the generated Dashboard Composer as a standalone project:

cd dashboard-composer
npm install
npm run dev

Use npm run build before deployment. The generated project pins a compatible Ceramic package range and splits the optional Puck editor dependencies into separate production chunks; the validated Layout JSON and registry renderer remain usable without opening the visual editor.

Semantic UX recipes

For optional reusable UI parts, the coding agent uses find_ui_parts({goal}), get_ui_part({id, theme?}) or prepare_ui_composition({goal, theme?}). The user never chooses or assembles patterns. The agent checks candidate fit, retrieves only needed exports and connects host-owned state. No useful match means no pattern is required. User/room theme wins; otherwise Cloudblur. Read utopia-ds docs ui-parts --dense. Existing list_patterns, get_pattern, and prepare_pattern_adaptation remain available for abstract interaction recipes; recipes are not executable templates.

Guided MCP navigation

Ask your local AI to “Start Ceramic” (or “세라믹 시작”). The ceramic_guide tool returns a numbered task menu, one input question at a time, examples, and Back/Main menu navigation. It covers logo, Brandbook, semantic theme, website, pitch deck/one-pager, room connection, output upload, and documentation.

The client should show the choices in the user's language and preserve the returned screen and values between calls. Reuse answers the user already supplied. Every normal tool response also includes a short nextSteps text block; existing structuredContent remains unchanged. Match numbers against the currently displayed choices and use that choice's call when present. Choices with action or inputHint describe local AI work or a question, not an automatic MCP mutation.

The guide is read-only and does not persist answers into a room brief, run a generation model, upload files, or publish. Existing preparation tools remain the authority for missing room prerequisites. Uploads require verified room access and a user-requested output path. Connection credentials must stay in the private connection file.

Menus are rendered by the MCP host: text choices work without native buttons. Server initialization includes guidance instructions, but each host controls whether it follows or automatically displays them. The user can always invoke the guide explicitly.