開発ガイド

NOTE

この文書は、Jumpu UI のリポジトリでの開発に参加する開発者を対象に書かれています。

Jumpu UI を利用するにあたっては必ずしも重要ではないので、この文章は読み飛ばしてください。

準備

パッケージマネージャーとして pnpm を採用しています。ご自身の開発環境に適切な方法でインストールしてください。

クイックスタート

# パッケージのインストール
pnpm install
# コードの検査
pnpm -r lint
# 開発サーバーの起動
pnpm -r dev

CSS の書き方

packages/tailwindcss/stylelint.config.mjs が規約を強制します。 ここでは、その規約が何を守っているのかを書きます。

ショートハンドを使わない

padding、margin、border、background、transition、font、flex、grid など 23 のプロパティを禁止しています。

ショートハンドは、書かなかった副プロパティを初期値に戻します。 background: red と書くと background-image が消え、transition: 100ms と書くと transition-delay が消えます。 コンポーネントの CSS でこれが起きると、利用側から見て理由のわからない挙動になります。

/* 使わない */
padding: --spacing(2) --spacing(4);

/* こう書く */
padding-block: --spacing(2);
padding-inline: --spacing(4);

余白と大きさは --spacing() か --spacing-relative で書く

padding-*、margin-*、gap、width、height に --spacing(n) を書けるよう、stylelint が受け付ける構文を拡張しています。 任意の数値は禁止していないため、尺度に沿った値を使うことは書き手が守ります。

尺度から外れた値が混ざると、Spacing に書いてある尺度が実態と合わなくなります。

文字サイズに追従させたい余白には calc(var(--spacing-relative) * n) を使います。 どちらを選ぶかの判断は Spacing を参照してください。

プロパティの並び順

stylelint-config-recess-order に従います。 表示、位置、寸法、文字、装飾の順に並びます。

並び順が決まっていると、2 つのコンポーネントの CSS を比べたときに、差分が構造ではなく値として見えます。

クラス名の規約

クラス名を定義するのはコンポーネントの粒度だけです。 .jumpu-button__icon のような下位のクラスは作りません。 子要素は要素型セレクターか属性セレクターで指します。

/* 使わない */
.jumpu-tag__close { … }

/* こう書く */
.jumpu-tag {
  [role="button"] { … }
}

この規約は lint では強制していません。 新しいコンポーネントを足すときに、意識して守ってください。

理由は Principles に書いています。

ドキュメントを書く

ページを書く・推敲するときの手順、分類の判断、文章の規範は、リポジトリの .claude/skills/write-design-guideline/ にまとめています。

ビジュアルリグレッションテスト

このドキュメントの ```html preview で書いた例の描画を 1 つずつ撮影し、baseline の画像と比べます。 それ以外の方法で書いた見本（Tokens の色見本など）は対象外です。

baseline は packages/docs/vrt/__screenshots__/ にあり、ページと見出しごとに画像が並びます。 baseline は「VRT update」ワークフローでのみ生成・更新します。 開発者の環境で撮った画像は、他の開発者が正しさを確かめられないためです。 比較は push のたびに GitHub Actions の「VRT」ワークフローが行います。

差分が出たとき

1. 失敗したワークフローの artifact vrt-report を開き、差分を確認します
2. 意図した変更なら、Actions の「VRT update」ワークフローを、そのブランチを選んで実行します
3. baseline を更新するコミットがブランチに積まれるので、画像の差分を PR でレビューします

「VRT update」は main では実行できません。 このワークフローの push では「VRT」が起動しないため、比較し直すには次の push を待つか「VRT」を手動で実行します。

ローカルで実行する

pnpm --filter @jumpu-ui/docs build
pnpm --filter @jumpu-ui/docs exec playwright install chromium
pnpm --filter @jumpu-ui/docs vrt

ローカルでは CI とフォントなどが異なるため、差分がなくても失敗することがあります。