Home
Softono
serendie

serendie

Open source MIT TypeScript
Website GitHub
53
Stars
5
Forks
3
Issues
1
Watchers
1 week
Last Commit
JavaScript Libraries & Components Design Systems & Tokens

About serendie

Adaptive UI component library as part of Serendie Design System by Mitsubishi Electric

Platforms

Web Self-hosted

Languages

TypeScript

Links

Website Source Code
s
Published by
serendie
Visit View Profile

README.md

View on GitHub

Serendie Design System

GitHub NPM Version Storybook X


Serendie Design Systemは三菱電機によるオープンなデザインシステムです。
デザイントークンやSerendie Symbolsなど複数のリポジトリから構成されています。本リポジトリはSerendie UIを扱います。

Serendie UI

次のような特徴を持つ、ReactベースのUIコンポーネントライブラリです。

使い方

インストール

デザイントークンも同梱されます。

npm install @serendie/ui

プロジェクトへの導入

rootのCSSに対して下記を指定してください。1行目は、Serendie UIに対して、スタイルを適切に当てるためにカスケードレイヤーの指定をするもの、2行目は同梱のデザイントークンやデフォルトスタイルを読み込むものです。

@layer reset, base, tokens, recipes, utilities;
@import "@serendie/ui/styles.css";

コンポーネントを使う

各Componentのpropsについては、ドキュメントや、Storybook、Figma Code Connectを参照してください。

import { Button } from "@serendie/ui";

<Button size="medium">Login</Button>;

Next.js App Routerでの使用

Next.js App RouterのServer Componentから使用する場合は、@serendie/ui/clientからインポートすることで、use clientディレクティブを記述する必要がなくなります。

// app/page.tsx - Server Component
import { Button } from "@serendie/ui/client";

export default function Page() {
  return <Button size="medium">Login</Button>;
}

Client Componentでも同様に使用できます：

// app/client-component.tsx - Client Component
"use client";
import { Tabs, TabItem, ModalDialog } from "@serendie/ui/client";

export default function ClientComponent() {
  // インタラクティブなコンポーネントも問題なく動作します
  return <Tabs defaultValue="tab1">...</Tabs>;
}

テーマ切り替え

Serendie Design Systemには5つのカラーテーマ (konjo, asagi, sumire, tsutsuji, kurikawa) とダークモードがあります。各テーマについてはこちらを参照してください。

SerendieProviderのcolorThemeとcolorModeを使って、テーマとカラーモードを設定できます。

import { SerendieProvider } from "@serendie/ui";

function App() {
  return (
    <SerendieProvider lang="ja" colorTheme="konjo" colorMode="system">
      {/* アプリケーション全体 */}
    </SerendieProvider>
  );
}
  • colorTheme: カラーテーマ（konjo | asagi | sumire | tsutsuji | kurikawa、デフォルト: konjo）
  • colorMode: カラーモード（system | light | dark、デフォルト: light）

colorMode="system"を指定すると、OSの設定に応じてライト/ダークモードが自動的に切り替わります。

FOUC（フラッシュ）の防止

SSR環境（Next.jsなど）では、ページ読み込み時にテーマが一瞬ちらつく（FOUC）ことがあります。ColorSchemeScriptを<head>内に配置することで、HTMLの描画前にテーマを適用しFOUCを防止できます。

// Next.js App Router: app/layout.tsx
import { SerendieProvider, ColorSchemeScript } from "@serendie/ui";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <SerendieProvider lang="ja" colorTheme="konjo" colorMode="system">
      <html suppressHydrationWarning>
        <head>
          <ColorSchemeScript />
        </head>
        <body>{children}</body>
      </html>
    </SerendieProvider>
  );
}

SerendieProviderを<html>の外側に配置することで、ColorSchemeScriptはContextからテーマ設定を自動取得します。テーマの設定を1箇所にまとめられるため、値の不整合を防ぐことができます。

SerendieProviderを使わない場合や、ColorSchemeScriptをProvider外で使う場合は、propsで直接指定することもできます。

<ColorSchemeScript colorTheme="konjo" colorMode="system" />

data-panda-theme属性による直接制御

SerendieProviderを使用せずに、data-panda-theme属性を直接設定してテーマを切り替えることもできます。

<html data-panda-theme="asagi"></html>

スタイリングライブラリと併用する

マージンを微修正したいなど、Serendie UIのスタイルをカスタムしたいシーンでは、プロジェクト側にスタイリングライブラリ(CSS-in-JSなど)を導入してください。どのスタイリングライブラリでも併用は可能ですが、ここではSerendie UIの内部でも使用しているPanda CSSの例を紹介します。

SerendiePresetの追加

Panda CSS導入後に生成されるpanda.config.tsに下記を追記することで、Panda CSSのPresetとSerendie Design Systemのデザイントークンを繋ぎこみます。

+import { SerendiePreset } from "@serendie/ui";

export default defineConfig({
+  jsxFramework: "react",
+  presets: [SerendiePreset],
});

より実践的な例は、こちらのサンプルプロジェクトを参考にしてください。

多言語対応

Serendie UIは日本語・英語の多言語対応をサポートしています。SerendieProviderを使用して、アプリケーション全体の言語を設定できます。なお、 SerendieProvider の利用は必須ではありません。利用しない場合は、デフォルトで日本語が適用されます。

import { SerendieProvider } from "@serendie/ui";

function App() {
  return (
    <SerendieProvider lang="ja">{/* アプリケーション全体 */}</SerendieProvider>
  );
}

Next.js App Routerでの多言語対応

// app/layout.tsx
import { SerendieProvider, ColorSchemeScript } from "@serendie/ui";

export default function RootLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: { lang: "ja" | "en" };
}) {
  return (
    <SerendieProvider lang={params.lang} colorTheme="konjo" colorMode="system">
      <html lang={params.lang} suppressHydrationWarning>
        <head>
          <ColorSchemeScript />
        </head>
        <body>{children}</body>
      </html>
    </SerendieProvider>
  );
}

APIを詳しく知る

Serendie UIはヘッドレスUIとして、Ark UIを内部的に利用しており、各コンポーネントのAPIはArk UIを継承します。Selectコンポーネントなどインタラクションが複雑なコンポーネントは、Ark UIのAPIリファレンスを合わせて参照してください。

Serendie UI開発者向け

Serendie UIに新しくコンポーネントを追加する場合は、Ark UIをベースにしてください。

npm run dev
npm run build

Figma Code Connect

Serendie UIでは、Figma Code ConnectをStorybookと繋ぎこむ形で導入しています。下記のコマンドで各コンポーネント毎のstoriesファイルの内容を、Figmaにpublishします。

npm run connect:publish

storiesファイルに変更が入ると上記がGitHub Actionsによって実行されます。

翻訳データの管理

Serendie UIの翻訳データはsrc/i18n/dictionary.tsで管理されており、Figma Variablesと同期できます。

コンポーネント内での翻訳の使用

useTranslationsフックを使用して、コンポーネント内で翻訳テキストを取得できます：

import { useTranslations } from "@serendie/ui";

function MyComponent() {
  const t = useTranslations();

  return (
    <div>
      {/* 変数なし */}
      <label>{t("common.required")}</label>

      {/* 変数あり - {{key}} プレースホルダーを使用 */}
      <span>{t("pagination.page", { page: 5 })}</span>
    </div>
  );
}

翻訳辞書では{{key}}形式のプレースホルダーを使用します：

// src/i18n/dictionary.ts
export const dictionary = {
  ja: {
    "common.required": "必須",
    "pagination.page": "{{page}}ページ目",
  },
  en: {
    "common.required": "Required",
    "pagination.page": "Page {{page}}",
  },
} as const;

環境設定

.envファイルに以下を設定してください：

FIGMA_ACCESS_TOKEN="YOUR_TOKEN"
FIGMA_FILE_KEY="YOUR_FILE_KEY"
# FIGMA_TRANSLATION_COLLECTION="_i18n"  # オプション（デフォルト: _i18n）

翻訳管理コマンド

# Figmaから翻訳データを取得して src/i18n/dictionary.ts を更新
npm run locales:pull

# ローカルの翻訳データをFigma Variablesに反映
npm run locales:push

# 翻訳データの整合性チェック（キーの不足や空文字のチェック）
npm run locales:lint

翻訳データの詳細についてはscripts/locales/README.mdを参照してください。

Resources

Serendie Design Systemは、Serendie UI (本リポジトリ) のほか以下の関連リポジトリから構成されています。

Package name Location Description
@serendie/design-token serendie/design-token W3C Design Token Format Moduleの仕様で定義されたSerendie UIのベースとなるデザイントークン
@serendie/symbols serendie/symbols Serendieらしい300種類以上のSVGアイコン集
@serendie/figma-utils serendie/figma-utils Figma REST APIを用いて、@serendie/design-tokenとFigma Variablesの同期を行うためのユーティリティー集
@serendie/style-dictonary-formatter serendie/style-dictonary-formatter デザイントークンを各プラットフォームに展開するためのamzn/style-dictonaryのフォーマッタ

Examples

主要パッケージの導入サンプルとして、serendie/bootcampを用意しています。また三菱電機内ではハンズオン形式で使い方を紹介するブートキャンプを開催しています。

サブブランド対応

Serendie Design Systemは三菱電機の有する多様な事業に適応することがコンセプトの一つです。

@serendie/desigon-tokenおよび@serendie/uiは、デフォルトでSerendieのVisual Identity (VI)を継承しますが、各事業ブランドのVIに合わせてテーミングできるよう社内向けにserendie/subbrands-templateを整備しています。

詳しくはSerendie Design Systemチームまでお問い合わせください。

License

各パッケージはMITライセンスの下で配布されています。 詳しくはLICENSEを参照してください。