--- title: "Web" description: "Tanrei の CSS トークンと Web Components を、どの Web プロジェクトでも使えます。" url: "https://tanrei.chnotchy.com/ja/getting-started/web/" last_updated: 2026-10-23T21:17:12.000Z --- # Web > Tanrei の CSS トークンと Web Components を、どの Web プロジェクトでも使えます。 `@tanrei/web` には 2 つのものが入っています。デザイントークンを CSS カスタムプロパティとして収めたスタイルシートと、Lit で作った標準準拠のカスタム要素です。特定のフレームワークは必要ありません。 > [!WARNING] > **プレリリース** > > `0.1.0-next.0` を npm の dist-tag `next` で公開しています。`0.1.0` までは `@tanrei/web@next` をインストールしてください。0.x のプレリリースのあいだは後方互換を保ちません。どのプレリリースも、先に非推奨の期間を置くことなく何でも壊すことがあり、何を壊したかはその changeset に書いてあります。 ## インストール ### npm から ```sh npm install @tanrei/web ``` ### ソースから 公開される前の `main` のソースを使うには、Git、Node 22.22 以降、pnpm 12 が必要です（`corepack enable` で、リポジトリが固定しているバージョンが使えます）。リポジトリのクローンでパッケージをビルドしてパックし、パックしたファイルをプロジェクトにインストールします。 ```sh git clone https://github.com/chnotchy/tanrei.git cd tanrei pnpm install pnpm --filter @tanrei/web build pnpm --filter @tanrei/web pack --pack-destination ../tanrei-packages ``` ```sh # プロジェクトで：パッケージを書き出したフォルダーへのパス npm install path/to/tanrei-packages/tanrei-web-*.tgz ``` パックしたファイルには、リリースで公開するものがそのまま入っているので、以下の手順はすべて同じように動きます。ソースの新しい状態を取り込むには、pull してからビルドとパックをやり直し、新しいファイルをインストールします。 ## 使い方 1. スタイルシートを一度だけ、できるだけ早い段階で読み込みます。どれもカスケードレイヤー（`tanrei.*`）に包まれているので、自分のスタイルが常に優先されます。 ```js import '@tanrei/web/tanrei.css'; ``` `tanrei.css` は、すべてを 1 つにまとめたファイルです。ページのベース、トークン、要素なしで描くパーツ（テキストスタイル、テーブル、アコーディオンなど）のスタイルシートが入っています。使うものだけを読み込むなら、トークンと、必要ならベースを読み込み、それらのスタイルシートは要るものだけを足します。 ```js import '@tanrei/web/tokens.css'; import '@tanrei/web/base.css'; // ページをシステムのサーフェス、文字色、本文の書体にし、body の余白をなくす ``` ベースは、ページそのものにサーフェスの色を、自分のテキストに on-surface の色と本文の書体を与え、ブラウザーが body に付ける余白を取り除きます。ベースがなければ、ページはブラウザーの既定のままです。 2. 自分のデザインシステムのコンポーネントを登録します。使う要素だけをインポートすることもできます。 ```js import '@tanrei/web'; // プリセットでは、代わりにそのエントリーを: m3-like、m3-expressive-like、cupertino import '@tanrei/web/m3-like'; // または、要素を 1 つずつ: import '@tanrei/web/components/button'; ``` `@tanrei/web` が登録するのは既定のシステムが持つコンポーネントだけなので、その上のプロダクトから、システムにないコンポーネントには手が届きません。プリセットのエントリー `@tanrei/web/` はそのプリセットが持つものを、`@tanrei/web/all` はパッケージのすべてのコンポーネントを登録します。[セグメントボタン](https://tanrei.chnotchy.com/ja/components/segmented-button/)のようにプリセットにしかないコンポーネントも、意図して使うことはできます。自分のシステムのレイヤーで取り込み、そのコンポーネント自身のモジュールを読み込みます。 `@tanrei/web/…` という指定子はパッケージのエクスポートで、バンドラー（Vite、webpack、esbuild）が解決します。バンドラーがない場合、ブラウザーは `` や ` ``` 3. 要素を、ほかの HTML と同じように使います。 ```html デプロイ キャンセル ``` 4. プロダクトの言葉を渡します。コンポーネントは自分の言葉を持ちません。必須・任意のタグのテキストや閉じるボタンの名前などは、プロダクトのものです。まずはすべてを平易な英語にするなら、英語の言葉のパックを一度だけ import します。 ```js import '@tanrei/web/words/en'; ``` どれかを変えるとき、または別の言語の言葉を渡すときは、そのあとで `setWords()` を呼びます。渡した言葉はパックの言葉に優先し、要素に書いた言葉はその両方に優先します。 ```js import { setWords } from '@tanrei/web'; setWords({ requiredText: 'Mandatory' }); setWords({ requiredText: '必須', optionalText: '任意', closeLabel: '閉じる' }, { lang: 'ja' }); ``` パックも自分の言葉もなくてもコンポーネントは動作し、どの言葉が足りないかをコンソールで知らせます。[言葉](https://tanrei.chnotchy.com/ja/foundations/words/)を参照してください。 ## 要素のマニフェスト エディターやコーディングエージェントは、パッケージの要素を [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) の `@tanrei/web/custom-elements.json` から読みます。すべての要素の属性、プロパティ、イベント、スロット、パーツが載っていて、プロダクトから触れないものは載っていません。`@tanrei/web/custom-elements/.json` にはシステム `` が持つ要素だけが載っているので、1 つのシステムで使うツールはそれ以外を提案しません。 ## テーマとコントラスト トークンの値は `light-dark()` を使っているので、使われている要素の `color-scheme` に従います。何も設定しなければ OS の設定に従い、`prefers-contrast: more` のときは高コントラストのスキームに切り替わります。 自分で決めたいときは、属性を設定します。 ```html ``` > [!NOTE] > **ノート** > > どちらの属性も、`` にも任意のサブツリーにも使えます。生成されるスタイルシートは、トークン一式を `:root, [data-tanrei-contrast]` に宣言しています。そのため、入れ子の要素に `data-tanrei-contrast` を付けると、システムの色だけでなく、その中のコンポーネントトークンも、そのコントラストレベルで解決し直されます。 ### 選んだテーマを保つ プロダクトでテーマを選べるなら、選んだものを保存し、ページが最初に描かれる前に `` に付けます。あとから動くスクリプトで付けると、ページは最初の 1 フレームだけシステムのテーマで表示されます。`@tanrei/web/theme-script` はその両方をします。`themeScript()` は `` のスタイルシートより前にインラインで書く小さなスクリプトで、`saveTheme()` は選んだテーマを保存してすぐに描きます。 ```js import { loadTheme, saveTheme } from '@tanrei/web/theme-script'; saveTheme('dark'); // 'light'、'dark'、または OS に従い直す 'system' loadTheme(); // 保存されているもの: 'light'、'dark'、'system' ``` Next.js（App Router）では、ルートのレイアウトにインラインで書きます。`suppressHydrationWarning` を付けるのは、React がハイドレートする前にスクリプトが `` の属性を変えるからです。 ```tsx // app/layout.tsx import { themeScript } from '@tanrei/web/theme-script'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( ``` このスクリプトは小さく、素直に書いてください。古いものも含め、訪れた人のブラウザーがすべてこれを実行します。静的な `import` にすると、ブラウザーはこのスクリプトより先にアプリを読み込むので、アプリを解析できない古いブラウザーでは確認そのものが動きません。`import()` なら、確認が済んでから読み込みます。 ## テスト ### ブラウザーで動かす Tanrei の要素は、ブラウザーが実装している機能の上に作られています。シャドウルート、`ElementInternals`（フォームコントロールの値と妥当性、カスタムステート）、Popover API、``、そしてレイアウトです。jsdom と happy-dom はその一部しか実装していません（happy-dom には `attachInternals()` も Popover API もありません）。そのため、描画した時点で要素が例外を投げたり、拒否された Promise が残ったり、要素が前提にしているサイズやフォーカス順、トップレイヤーがないまま描画されたりします。Tanrei はこれらの環境をサポートしておらず、足りない機能の代わりになるもの（スタブ）も提供していません。要素が例外を投げないようにするだけの代用品を置くと、どのブラウザーにもない振る舞いでテストが通ってしまうからです。 Tanrei の要素を描画するテストは、実際のブラウザーで動かしてください。 - [Vitest のブラウザーモード](https://vitest.dev/guide/browser/)を Playwright プロバイダーで使えば、コンポーネントのテストを Vitest に置いたまま、Chromium、Firefox、WebKit で動かせます。 - [Playwright Test](https://playwright.dev/docs/intro) は、ページや一連の操作の流れを動かします。 Tanrei の要素を描画しない、自前のロジックのテストは、Node や jsdom、happy-dom のままでかまいません。Tanrei 自身のテストは、Chromium、Firefox、WebKit で、Playwright と axe-core を使って動かしています。 ### 要素を探す ほとんどの要素は、自分自身ではなくシャドウルートの中のネイティブ要素（`