Serendie Design System(@serendie/ui, @serendie/symbols, @serendie/design-token)の概要・セットアップ手順・デザイントークンの使い方を提供し、詳細情報を Serendie MCP から得られるように案内する。Serendieを使った実装、コンポーネントやアイコンの使い方、デザイントークンの選び方、PandaCSS連携、テーマ切り替え、SerendieProviderの設定など、Serendieに少しでも関連する質問でトリガーすること。@serendie/ui のインポートがコード内に存在する場合も必ずトリガーすること。
Serendieが提供するライブラリの利用者(Serendie Design System に準拠したアプリケーションを構築する開発者)を対象としている。ライブラリ自体の開発やデザインシステムの運用に関する情報は含まない。
三菱電機のSerendie Design Systemが提供するWebフロントエンド向けのライブラリ群。ReactベースのUIライブラリ @serendie/ui など、複数の関連パッケージから構成される。
Serendieが提供・メンテナンスしているライブラリは下記の通り。
| パッケージ | 役割 |
|---|---|
@serendie/ui | Serendie UIと呼ばれる。UIコンポーネントを提供する中核ライブラリ。Figma上のデザインライブラリ (Serendie UI Kit) と対応している。 |
@serendie/design-token | デザイントークンを提供する。 Panda CSS用トークンの他に、CSS Variables形式などでも提供されており、Serendie UIとは独立して使用も可能。React外の環境でデザイントークンのみ利用する場合を想定。 |
@serendie/symbols | Serendie Symbolsと呼ばれる。300種類以上のアイコン(React環境前提)を提供。Serendie UIに同梱されるが、独立して使用も可能 |
Serendie UIは、Ark UI(ヘッドレスUIライブラリ)およびPanda CSS(スタイリングライブラリ)に基づき開発されている。特に各コンポーネントをユーザー環境に合わせたカスタマイズをする際に、下記のAPI Docsを参照すること。
| パッケージ | ユーザーへの影響 | API Docs |
|---|---|---|
@ark-ui/react | 同梱されるためユーザーがプロジェクトに導入する必要は無し。Serendie UIの各コンポーネントはArk UIを継承するため、適宜Ark UIのドキュメントを参照すること。 | https://ark-ui.com/llms.txt |
@pandacss/dev | ユーザーのプロジェクト導入は任意だが、スタイリング時にSerendie UIとの親和性は高い。 | https://panda-css.com/llms.txt |
リモートMCPサーバーであるSerendie MCP (https://serendie.design/mcp) が提供されている。詳細な情報は Serendie MCPの各ツールから取得すること。
| ツール | 用途 |
|---|---|
get-components | コンポーネント一覧の取得 |
get-component-detail | 特定コンポーネントの Props・使用例の取得 |
get-design-tokens | デザイントークン一覧の取得 |
get-design-token-detail | 特定デザイントークンの値・使用例の取得 |
get-symbols | アイコン一覧の取得 |
get-symbol-detail | 特定アイコンの詳細・使用例の取得 |
search-serendie-guideline | 設計指針やアセットの使い方などガイドラインの検索 |
なお、同等の情報をドキュメントサイトおよびStorybookとしても提供している。
npm install @serendie/ui
CSSのルートに以下を追加すること。この設定が抜けると正しくCSSが適用されない。@layer の宣言順序がスタイルの優先度を決定するため、順序を変えるとスタイルが壊れたり意図しない上書きが発生する。
@layer reset, base, tokens, recipes, utilities;
@import "@serendie/ui/styles.css";
なお、Reset CSS は @serendie/ui に同梱済みのため、別途追加してはいけない。
ユーザーの環境に合わせて、必要なコンポーネントをインポートして利用する。
// Serendie UIのインポート (通常)
import { TextField, Button, Select } from "@serendie/ui";
// use client 適用済みのSerendie UI(Next.js環境)
import { TextField, Button } from "@serendie/ui/client";
// PandaCSS スタイルユーティリティ(PandaCSS導入時)
import { css } from "@serendie/ui/css";
// PandaCSS レイアウトコンポーネント(PandaCSS導入時)
import { Box, Center, Flex, Stack, VStack } from "@serendie/ui/jsx";
@serendie/ui の依存パッケージとしてインストールされるため、追加インストールは不要。@serendie/ui を使わずアイコンのみ利用する場合は npm install @serendie/symbols で個別導入する。
使用例:
import {
SerendieSymbolHome, // homeアイコン (outline)
SerendieSymbolSettingsFilled, // 設定アイコン (filled)
} from "@serendie/symbols";
利用可能なアイコンはSerendie MCPの get-symbols / get-symbol-detail で確認すること。
ユーザープロジェクトに、PandaCSS を導入すると、デザイントークンを JSX 内で直接利用できるなど、よりシームレスにSerendie UIを利用できる。
panda init は親ディレクトリに既存の panda.config.ts がある場合、生成をスキップすることがある。その場合は手動で panda.config.ts を作成すること。
インストール:
npm install -D @pandacss/dev
npx panda init --postcss
package.json に "prepare": "panda codegen" を追加し、panda.config.ts で SerendiePreset を presets に指定する。これによりデザイントークンやレシピがPandaCSSから利用可能になる。
その他のPandaCSS設定は公式ドキュメント (https://panda-css.com/llms.txt) を参照のこと。
import { SerendiePreset } from "@serendie/ui";
export default defineConfig({
presets: [SerendiePreset],
jsxFramework: "react",
include: ["./src/**/*.{js,jsx,ts,tsx}"],
// その他はPandaCSSのドキュメントに従って設定
});
この設定により、下記のようにデザイントークン名をコード内で扱うことができる。なお、このデザイントークン名は、Figmaのデザインライブラリ (Serendie UI Kit) のデザイントークン名 (Figma Variables) と一致する。
<Box my="sd.system.dimension.spacing.sixExtraLarge">
また、css()メソッドを利用して同様のことができる。
import { css } from "@serendie/ui/css";
// ...snip...
<div className={css({ my: "sd.system.dimension.spacing.sixExtraLarge" })}>
コンポーネントは以下のカテゴリに分類される。一覧・詳細は Serendie MCP の get-components / get-component-detail で取得すること。
バリアント Props 名はコンポーネントごとに異なる(例: Button は styleType、Badge は styleColor)。 他のUIライブラリでみられる variant ではないので、必ず get-component-detail または TypeScript の型定義で確認すること。
get-design-tokens / get-design-token-detail で確認することより詳細はSerendie MCPの search-serendie-guidelineでキーワード検索して確認すること。
sd.system.*)」と「リファレンストークン(sd.reference.*)」の2層から構成される。システムトークンはリファレンストークンを参照する。sd.system.dimension のように3階層目で表現される。sd.system.dimension.spacingのように4階層目で表現されるexpanded, compact) は、デバイス環境を示す。expandedはPC/Laptop環境、compactはスマートフォン環境に対応している。レスポンシブデザインの場合は、breakpointごとに使い分けるなど、ユーザーのプロジェクトに合わせて使い分けること。NG: px値やHEXカラーを直接指定している
css({
padding: "16px",
margin: 8,
color: "#333",
fontSize: "16px",
borderRadius: "8px",
boxShadow: "0 2px 4px rgba(0,0,0,0.1)",
});
OK: デザイントークンを使用している
css({
p: "sd.system.dimension.spacing.medium",
m: "sd.system.dimension.spacing.small",
color: "sd.system.color.component.onSurface",
textStyle: "sd.system.typography.headline.small_expanded", // Panda CSSのText Styleを利用 (後述)
borderRadius: "sd.system.dimension.radius.medium",
boxShadow: "sd.system.elevation.shadow.level2",
});
textStyle は PandaCSS の Text Styles 機能であり、fontSize / fontWeight / lineHeight 等を個別に指定するのではなく textStyle で一括指定する。必須ではないが、記述が簡潔になるため、PandaCSSを利用する場合は利用が推奨される。
NG: リファレンストークンやセマンティクスの合わないトークンを使っている
css({
color: "sd.reference.color.scale.gray.500", // リファレンストークンを直接使用
borderColor: "sd.system.color.component.onSurface", // テキスト用トークンをボーダーに (セマンティクスの不一致)
bg: "sd.system.color.interaction.disabled", // interactionロールは状態変化専用。「グレーの背景が欲しいから」と装飾目的で流用してはいけない
});
OK: 用途に合ったシステムトークンを使っている
css({
color: "sd.system.color.component.onSurface", // テキスト色にはonSurface
borderColor: "sd.system.color.component.outline", // ボーダーにはoutline
bg: "sd.system.color.component.surface", // 背景にはsurface
});
<html data-panda-theme="asagi"></html>
SerendieProvider をアプリケーションのルートで利用すること。カラーテーマも SerendieProvider から指定可能ColorSchemeScript を <head> に配置して FOUC(テーマのちらつき)を防止するimport { SerendieProvider } from "@serendie/ui";
<SerendieProvider lang="ja" colorTheme="konjo" colorMode="system">
{/* アプリケーション全体 */}
</SerendieProvider>;
コンポーネント内で現在のテーマ情報を取得したい場合は useThemeContext() フックが利用可能。また、現時点ではダークモードは konjo-dark テーマのみ実装されており、他のカラーテーマではダークモード指定時に konjo-dark へフォールバックする。
詳細は@serendie/uiのREADME の「テーマ切り替え」「多言語対応」セクションを参照。
プロジェクトの制約によりPandaCSSを利用できないが、Serendieのデザイントークンを適用したい場合は、CSS Variablesが利用可能。
.my-class {
color: var(--sd-system-color-impression-primary);
margin: var(--sd-system-dimension-spacing-sixExtraLarge);
}