Lily を始める

インストール

Lily は 1 つの Git モノレポにあり、フレームワークごとにヘッドレスライブラリ、ヘルパーパッケージ、サンプルアプリのディレクトリがあります。試す最も早い方法は、モノレポをクローンして、お使いのスタックのヘッドレスライブラリを開くことです。

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-react-headless
pnpm install

他のフレームワークでも同じパターンです。

• @lilydesignsystem/html-headless — インストール不要。.html ファイルをコピーします
• @lilydesignsystem/svelte-headless — pnpm install
• @lilydesignsystem/react-headless — pnpm install
• @lilydesignsystem/vue-headless — pnpm install
• @lilydesignsystem/angular-headless — pnpm install
• @lilydesignsystem/nunjucks-headless — pnpm install
• lily-design-system-blazor-headless — dotnet build

ヘッドレスライブラリは、クローンまたはベンダリングして使うように設計されています。ソースを正とし、必要なものをコピーしてください。 設定ヘルパーは、さらにビルドと公開のパイプライン（JS フレームワークは npm、Blazor は NuGet）を備えた、インストール可能なパッケージとしても提供されます。

ヘッドレスコンポーネントを使う

ヘッドレスコンポーネントは、セマンティックな HTML、ARIA、プロパティを提供しますが、CSS は含みません。各フレームワークでの Button は次のとおりです。

HTML

<button class="button" type="button" aria-label="Save">
  Save
</button>

Svelte

<script>
  import Button from "lily-design-system-svelte-headless/components/Button/Button.svelte";
</script>

<Button onclick={save}>Save</Button>

React

import Button from "lily-design-system-react-headless/components/Button";

<Button onClick={save}>Save</Button>

Vue

<script setup>
  import Button from "lily-design-system-vue-headless/components/Button.vue";
</script>

<Button @click="save">Save</Button>

Angular

import { Button } from "@lilydesignsystem/angular-headless";

@Component({
  imports: [Button],
  template: `<lily-button (click)="save()">Save</lily-button>`,
})

Blazor

<Button OnClick="Save">Save</Button>

Nunjucks

{% from "components/button/macro.njk" import button %}

{{ button({ text: "Save", type: "button" }) }}

スタイル付きのサンプルを使う

サンプルアプリには、CSS、ルート、完全なデモページが含まれています。試すいちばん早い方法は、SvelteKit、Next、Nuxt、Analog、Eleventy のサンプルアプリを起動して、/components のデモを見ることです。

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-sveltekit-examples
pnpm install
pnpm run dev

そのあと http://localhost:5173 を開き、/components を見て回ってください。

スタイルとデザイントークン

各コンポーネントは、ルート要素にケバブケースのクラスを 1 つ付けて表示されます。 たとえば <Button> は <button class="button"> を出力します。 スタイルは好きなように付けられます。

.button {
  background: var(--my-primary);
  color: #fff;
  padding: 0.75rem 1.5rem;
  border-radius: 0.5rem;
}
.button:hover { background: var(--my-primary-hover); }

Lily の既定のカラーパレット（サンプルアプリで使用）は次のとおりです。

• プライマリ: #2563eb
• 危険: #dc2626
• 警告: #f59e0b
• 成功: #16a34a
• ページの背景: #f9fafb
• カードの背景: #ffffff

これらは提案であり、必須ではありません。ご自身のブランドのパレットに置き換えても、Lily は問題なく対応します。

すぐに使えるテーマ

CSS をゼロから書きたくありませんか？Lily には、57 種類の独立したリファレンステーマが themes/ ディレクトリに付属します。それぞれが Lily のクラスフックを対象とする 1 つのスタイルシートで、 リンクするだけでスタイルが付きます。

<link rel="stylesheet" href="/assets/themes/united-kingdom-government-digital-service.css" />

用意されているテーマは次のとおりです。

• 公共部門 — NHS England、NHS Scotland、NHS Wales （それぞれ患者向けと実務者向けの種類）、GOV.UK GDS、U.S. Web Design System。
• ベンダーに着想を得たもの — Adobe Spectrum、Mozilla Protocol。
• 汎用 — light、dark、nord、dracula、wireframe など、さらに 30 種類あまり。

テーマのセレクターには :where(...) を使っているため、詳細度ではあなた自身の CSS が常に優先されます。実行時の切り替えには、下の theme-picker ヘルパーと組み合わせるか、 テーマ設定のチュートリアルに従ってください。

設定ヘルパー

各フレームワークには、8 つの小さなピッカーがあり、それぞれが独自の lily-design-system-{framework}-{package} パッケージです（それらをまとめる picker-bar もあります）。それぞれが、 ポップアップ（リストボックス、リンクの一覧、検索フォーム、date-time-picker の場合は日付選択ダイアログ）を開くヘッドレスのアイコンボタンで、ネイティブの <select> ではなく、SSR に対応し、CSS は含みません。

• theme-picker — 管理対象の <link> を差し替えることで実行時にテーマのスタイルシートを読み込み、ドキュメントに data-theme を設定し、必要に応じて localStorage に保存します。
• locale-picker — lang と dir（RTL の自動検出付き）を設定して、i18n ライブラリが追従できるようにします。翻訳そのものは行いません。
• text-size-picker — ドキュメントに data-text-size を設定します。各値をフォントサイズに対応づけるのは、あなたの CSS です。
• motion-picker — 訪問者のモーション軽減の設定を出発点として、ドキュメントに data-motion を設定します。 何を抑えるかは、あなたの CSS とスクリプトが決めます。
• search-picker — 検索フィールドを開くアイコンボタン。送信すると検索ページに移動します。設定ではなく、操作を担います。
• link-picker — アプリが定義するページリンク（ホーム、会社概要、お問い合わせ、プライバシーポリシーなど）のメニューを開くホームアイコン。 設定ではなく、操作を担います。
• share-picker — ネイティブの共有シートか、利用側が用意した共有先の一覧と、URL のコピーを開きます。 設定ではなく、操作を担います。何も適用せず、何も保存しません。
• date-time-picker — 日付、時刻、またはその両方のための、テキストフィールドと APG の日付選択ダイアログ。 設定ではなく、フォームの値を担います。ISO 文字列は <input type="date"> と相互に変換されます。

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-theme-picker

Svelte のカタログが正本です。React、Vue、Angular、HTML、Nunjucks、Web Components、Blazor への移植版は、約束事のひとつひとつまで一致しています。詳しくは ヘルパーのチュートリアルをご覧ください。

アクセシビリティ

コンポーネントは WCAG 2.2 AAA を目標としています。次のパターンに従っています。

• 汎用の <div> よりもセマンティックな HTML 要素。
• ラベルと入力を結びつける <label for="id">。
• 相互参照のための aria-labelledby / aria-describedby。
• エラー状態のための aria-invalid + aria-errormessage。
• 動的なコンテンツのための role="alert" と aria-live。
• 状態のための aria-pressed、aria-expanded、aria-current。
• グリッドのためのローヴィング tabindex。

フォーカスの表示は意図的に利用側が用意するものです。Lily は、あなたのデザインと衝突する既定のフォーカスリングを描くことはありません。 サンプルアプリは、全ルートで axe-core のクリーンなベースラインを保っています。

多言語化

ラベル、プレースホルダー、エラーメッセージ、ボタンの文言は、すべてプロパティです。ハードコードされた文字列はありません。 お好みの翻訳フレームワーク（Paraglide、i18next、vue-i18n、react-intl、.resx ファイルなど、何でも）を組み込んでください。

日付、数値、通貨については、コンポーネントは整形済みの文字列を受け取ります。 Intl.DateTimeFormat / Intl.NumberFormat / お好みのライブラリで整形し、その結果を渡してください。

locale-picker ヘルパーは、ドキュメントのルートに lang と dir を設定することで、 選ばれたロケールを i18n ライブラリに伝えます。

テスト

各フレームワークのサブプロジェクトには、そのフレームワークに合った構成のテストが付属します。

• HTML: 実ブラウザーで動かす WebDriverIO。
• Svelte: Vitest + @testing-library/svelte。
• React: Vitest + @testing-library/react。
• Vue: Vitest + @testing-library/vue。
• Angular: Vitest + TestBed（Analog の Vite プラグイン経由）。
• Nunjucks: レンダリングヘルパー付きの Vitest。
• Blazor: bUnit。

テストでは Vitest 組み込みのマッチャーだけを使い、 jest-dom のマッチャーは使いません。これでテストスイートの移植性が保たれます。 サンプルアプリには、Playwright のエンドツーエンドテスト、axe-core のアクセシビリティベースライン、レスポンシブのビューポート検査が加わります。

AI エージェント

このサイトは、ルートに llms.txt と llms.json を公開しています。これは、 llms.txt の規約に従うあらゆるツール向けの、最も重要なページを厳選した案内図です。

正式なモノレポには、さらに 2 つの Claude Skills があります。 lily-design-system-skill は、このシステムで開発する人向けに Lily の概念、用語、組み合わせパターンを扱う汎用スキルで、 lily-design-system-maintainer-skill は、モノレポで作業する人向けに必須ファイルの構成とツールを扱う技術的なスキルです。 どちらも 正式なモノレポのルートにあります。

トラブルシューティング

コントリビュート

Lily は若いプロジェクトで、協力を歓迎します。現在とくに役立つ貢献は次のとおりです。

• 新しいコンポーネント（とくに、確立されたデザインシステムのパターン）。
• 新しいテーマ。それぞれが独立した 1 つのスタイルシートで、最初のプルリクエストに適した範囲です。
• より良いサンプルのスタイル付け。可能なことを見せてください。
• サンプルアプリの文字列の翻訳。
• 最小限の再現手順を添えたバグ報告。
• スクリーンリーダーや支援技術によるアクセシビリティ監査。

issue とプルリクエストは github.com/LilyDesignSystem/lily-design-system へどうぞ。

コミュニティとサポート

• 質問とバグ報告 — github.com/LilyDesignSystem/lily-design-system で issue を開いてください。
• メール — メンテナーは joel@joelparkerhenderson.com を読んでおり、協力、助言、フィードバックを歓迎します。
• ミラー — Lily は Codeberg と GitLab にも公開されているので、お好みのフォージから参加できます。
• 行動規範 — このプロジェクトは標準的な行動規範に従います。親切に、善意を前提にしてください。

FAQ