デザインシステムの管理方法

デザインシステムは、プロジェクトの視覚的なルール（色、タイポグラフィ、余白）を定義します。画面に適用すると、すべての画面が同じ視覚言語に従います。SDK を使えば、Stitch の UI に触れることなくデザインシステムの作成、更新、適用ができます。

デザインシステムを作成する

import { stitch } from "@google/stitch-sdk";

const project = stitch.project("your-project-id");
const ds = await project.createDesignSystem({ displayName: "My Theme" });
console.log(`Created: ${ds.id}`);

displayName は Stitch の UI に表示される名前です。わかりやすい名前を付けましょう。「Brand Dark Mode」のほうが「DS 1」より良い名前です。

既存のデザインシステムを一覧表示する

const systems = await project.listDesignSystems();
for (const ds of systems) {
  console.log(`${ds.id}: ${ds.data?.displayName}`);
}

ID でデザインシステムを参照する

アセット ID をすでに知っている場合は、ネットワーク呼び出しを省略できます：

const ds = project.designSystem("existing-asset-id");

これは、サーバーから何も取得せずにハンドルを作成します。前の手順や Stitch UI で ID を把握している場合に使用します。

DESIGN.md から作成する

視覚的アイデンティティを定義した DESIGN.md をすでにお持ちですか？アップロードして、2 回の呼び出しでデザインシステムに変換できます：

import { readFileSync } from "node:fs";

const markdown = readFileSync("DESIGN.md", "utf-8");
const instance = await project.uploadDesignMd(Buffer.from(markdown, "utf-8").toString("base64"));
const ds = await project.createDesignSystemFromDesignMd(
  { id: instance.id, sourceScreen: instance.sourceScreen },
  "DESKTOP",
);

結果の適用方法や callTool の直接的な使い方を含む完全な手順については、DESIGN.md からデザインシステムを作成する方法を参照してください。

デザインシステムを更新する

const updated = await ds.update({ displayName: "Updated Theme" });

画面に適用する

デザインシステムを適用すると、新しい視覚トークンで画面が再レンダリングされます。必要なのは SelectedScreenInstance オブジェクトで、これはプロジェクトの画面インスタンスから取得します：

const projectData = await stitch.callTool("get_project", {
  name: `projects/${project.id}`,
});

// Extract screen instances
const instances = projectData.screenInstances.map((si: any) => ({
  id: si.id,
  sourceScreen: si.sourceScreen,
}));

// Apply the design system to all screens
const screens = await ds.apply(instances);
console.log(`Applied to ${screens.length} screens`);

インスタンスオブジェクトには id と sourceScreen だけを含めてください。位置やサイズなどの余分なフィールドがあると、「invalid argument」エラーになります。

完全なワークフロー：作成と適用

以下はエンドツーエンドのパターンです。プロジェクトを作成し、画面を生成し、デザインシステムを作成して適用します：

import { stitch } from "@google/stitch-sdk";

const project = await stitch.createProject("Themed App");

// Generate a few screens
const home = await project.generate("A landing page for a productivity app");
const settings = await project.generate("A settings page with dark theme toggle");

// Create and apply a design system
const ds = await project.createDesignSystem({ displayName: "Productivity Theme" });

// Get screen instances for applying
const projectData = await stitch.callTool("get_project", {
  name: `projects/${project.id}`,
});

const instances = projectData.screenInstances.map((si: any) => ({
  id: si.id,
  sourceScreen: si.sourceScreen,
}));

await ds.apply(instances);
console.log("Design system applied to all screens");