# Helsinkiデザインシステム

## Helsinkiデザインシステムのインターフェースプレビュー

選択するトピックが少なすぎる状態を試し、エラーリンクから該当箇所に移動して選択を修正し、レビュー画面から戻ってみてください。

## Helsinkiデザインシステムのデザインリファレンス

hds-core5.2.2 パッケージの CSSと公式フォームガイダンス。ネイティブスタイル、Arial フォールバック、独自の最小選択数ルールを使用しています。

### タイポグラフィのデザイントークン

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| --font-default | HelsinkiGroteskPro, Arial, sans-serif | 著作権で保護された Helsinkiのフォントは Core パッケージに含まれていません。デモではネイティブの Arial フォールバックを使用します。 |
| --fontsize-body-s/m/l/xl | 14 /16 /18 /20px | ルートの通常サイズでは、フィールドごとに任意のサイズを選ぶのではなく、役割に合ったサイズを選びます。 |
| --fontsize-heading-xxl/xl | 64 /48px | 大見出し。 |
| --fontsize-heading-xl-mobile | 40px | 明示的なトークンです。プレビューが 576px で切り替わるのは、アプリケーション独自の設定です。 |
| --fontsize-heading-l/m/s | 32 /24 /20px | 小見出し。 |
| --lineheight-s/m/l/xl | 1 /1.2 /1.5 /1.75 | ピクセル単位の高さではなく、倍率です。 |
### コンポーネントとレイアウトのスペーシング

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| Component scale | 2,4,8,12,16,24,32,40,48,56,64,72px | spacing-4-xs から spacing-5-xl まで。 |
| Layout scale | 16,24,32,48,64,96,128px | spacing-layout-2-xs から spacing-layout-2-xl まで。 |
| Breakpoints | 320,576,768,992,1248,1440px | xs から xxl まで。トークン値を宣言するだけでは、メディアクエリは作成されません。 |
| Container widths | 288,544,720,944,1200px | xs から xl までの参照幅。 |
| Checkbox geometry | 24px size;2px border;3px focus outline | 実際の Core5.2.2 CSS。 |
| Button minimum | 56px; square corners | 2px の境界線。パディングは spacing-s/l から算出します。 |
### セマンティックカラーとパレットカラー

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| Bus | #0000bf | チェックボックスの選択状態とプライマリボタンのデフォルトテーマ。 |
| Coat of arms / focus | #0072c6 | シティブルーとフォーカスの役割を区別します。 |
| Copper | #00d7a7 | アクセントパレット。デモのヘッダー線に使用します。 |
| Error / light | #b01038 /#f6e2e6 | バリデーションのフィードバックです。装飾用のBrickとは用途が異なります。 |
| Success / light | #007a64 /#e2f5f3 | 結果の確定を示す役割です。 |
| Info / alert | #0062b9 /#ffda07 | 情報と注意喚起の役割です。 |
| Text / secondary | #1a1a1a /#595959 | black-90とblack-60。 |
### フォームの構造と修正

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| Selection group | fieldset + legend | 凡例は選択内容を説明し、ラベルは各選択肢を説明します。 |
| Vertical items | hds-selection-group__items--vertical | 長い選択肢を無理に横一列に並べないでください。 |
| Error summary | Notification error variant with linked error list | フォーム見出しの下に配置し、送信に失敗したら見出しにフォーカスを移します。 |
| Inline error | hds-selection-group__error-text | 修正中も補助説明を表示したままにします。 |
| Application rule | At least two topics | 元のシナリオに合わせたバリデーションであり、HDSのチェックボックスの既定値ではありません。 |
## Helsinki デザインシステム完全ガイド

実際のインターフェースで、このデザインシステムを選び、適用し、レビューするための実践ガイドです。

詳しいガイダンス、実装の出発点、ソースへのリンクをまとめています。

## Helsinki デザインシステムのCoreとReactの境界

### 実際に使用する実装を選ぶ

> HDSには、Core CSS、Reactコンポーネント、デザイントークンが用意されています。このサンプルでは、例でダウンロードして内容を確認したhds-core5.2.2を固定して使用しています。リポジトリのリリース番号は個別のパッケージのバージョンと異なる場合があるため、リポジトリに新しいタグが付いていても、このサンプルがそのバージョンで動作する証拠にはなりません。

Coreは基本変数と個別のコンポーネントスタイルを提供しますが、ここで使用するフォームアプリケーションの状態管理は提供しません。選択、検証、確認、変更のロジックは、ネイティブなHTML入力と、ドキュメントに記載されたHDSのフォームパターンを基に独自に実装したJavaScriptのものです。

関連する仕様を確認する

## Helsinki デザインシステムのタイポグラフィとフォントの境界

### 代替フォントを明示して使用する

フォント変数では、HelsinkiGroteskProを最初に指定し、その後にArialとsans-serifを指定しています。CoreのREADMEには、著作権上の理由からHelsinkiのフォントファイルは含まれないと明記されています。このプレビューでは、使用制限のあるフォントをダウンロードしたり、ブランドの表示を正確に再現していると誤認させたりせず、代替フォントを使用しています。

本文の基本トークンは16px、行の高さは1.5です。heading-xlは48px、モバイル用トークンは40pxで、プレビューでは576pxを境に切り替えています。これらは名前付きの値ですが、CSS変数にブレークポイントを含めても、それだけでレスポンシブな動作が生まれるわけではありません。明示的なメディアルールは、アプリケーション側の構成に含まれます。

関連する仕様を確認する

## Helsinki デザインシステムにおける2つのスペーシング体系

### コンポーネント間の間隔とページ全体のリズムを分ける

HDSでは、コンポーネント用のスペーシング系列と、より大きなレイアウト用の系列を区別しています。前者は2、4、8、12、16、24pxから始まり、最大72pxまで広がります。レイアウト用のスペーシングは128pxまであります。spacing-layout-xlは有効な変数ですが、隣り合うチェックボックス間の間隔に使うと、グループが間延びしてしまいます。

チェックボックスのコンポーネントでは、コントロールのサイズを24px、枠線を2px、フォーカスアウトラインを3pxと定義しています。ボタンの最小サイズは56pxで、角は直角です。プレビューではこうした形状をそのまま使用し、フォームは公開されている基準幅720pxを上限とするアプリケーションコンテナ内に配置しています。

関連する仕様を確認する

## Helsinki デザインシステムにおけるフォームの色の役割

### パレット名とフィードバックの役割を混同しない

既定のインタラクティブテーマにはBus blueを使い、フォーカスアウトラインにはCoat of arms blueを使います。エラーのフィードバックには、それぞれ異なるベリー系の色と淡いエラー用背景色を使います。Copperなどのパレットアクセントはヘッダーに使えますが、目立つという理由だけでエラー用の色の代わりにしてはいけません。

選択グループのインラインエラーは、テキスト、コントラストのある左側の枠線、アイコンを組み合わせています。赤だけに頼ることはありません。エラーサマリー内のリンクには、フィールドに戻る手段だと認識しやすいよう、一般的なインタラクティブカラーを使います。

関連する仕様を確認する

## Helsinki デザインシステムにおけるチェックボックスグループの構成

### グループには1つの質問と複数の回答があります

ネイティブな構造は、凡例を含むfieldset、項目コンテナ、個々のチェックボックスのラッパーで構成されます。スタイルシートがこの関係を視覚状態に利用するため、各入力要素の直後にラベルを置きます。凡例は選択する内容を説明し、各ラベルは選択可能な項目を示します。

このデモでは、独自の業務ルールとして2つ以上の項目を選ぶよう求めます。複数の選択肢を選択したままにできるため、チェックボックスが適切です。ラジオボタングループは相互に排他的な選択を表すため、このタスクには適しません。フィールドセットのヒントは、バリデーションの前後を問わず表示されます。

```
<fieldset class="hds-selection-group" aria-describedby="topics-hint">
  <legend class="hds-selection-group__legend">Topics for your afternoon</legend>
  <p id="topics-hint">Choose at least two topics.</p>
  <div class="hds-selection-group__items hds-selection-group__items--vertical">
    <div class="hds-checkbox">
      <input class="hds-checkbox__input" type="checkbox" id="repair" value="Repair and reuse">
      <label class="hds-checkbox__label" for="repair">Repair and reuse</label>
    </div>
    <div class="hds-checkbox">
      <input class="hds-checkbox__input" type="checkbox" id="garden" value="Urban gardening">
      <label class="hds-checkbox__label" for="garden">Urban gardening</label>
    </div>
  </div>
</fieldset>
```

コードリファレンス

関連する仕様を確認する

## Helsinki デザインシステムにおけるエラーの関連付けと修正

### 問題にフォーカスを移し、入力内容は保持する

HDSでは、送信に失敗した後、フォーム見出しの下にエラーサマリーを表示することを推奨しています。リストのリンクからエラーのあるコントロールに移動でき、フォーカスはサマリーの見出しに移ります。このデモも同じ手順に従います。項目を0個または1個選んだ状態で確認すると、サマリーとインラインメッセージが表示され、リンクをクリックすると最初のチェックボックスにフォーカスが移ります。

最初の送信を試みた後は、選択内容が変わるたびに最小選択数を再確認します。2つ以上の項目を選ぶと、選択済みの入力を消去せずに、2つのエラー表示がどちらも消えます。再度送信に失敗した場合は、フォーカスがサマリーの見出しに戻ります。確認時にもルールを再チェックします。実際のサービスでは、クライアント側のフィードバックをサーバー側のバリデーションの代わりにしてはいけません。

1. 項目を選択せずに確認し、サマリーにフォーカスが移ることを確かめます。

2. リンクから移動し、項目を2つ選択してエラーが消えることを確かめます。

3. ローカルの確認画面を開き、項目を変更するために戻って、選択内容が保持されていることを確かめます。

関連する仕様を確認する

## Helsinki デザインシステムのアセットとサンプル一式

### 基本スタイルと使用するコンポーネントを読み込む

Coreパッケージでは、base.cssとコンポーネントのスタイルが分かれています。baseだけを読み込むと変数とタイポグラフィは利用できますが、チェックボックスや通知の構成は利用できません。このセットアップでは、このサンプルで使用するファイルを明示し、すべてのコンポーネントを含むバンドルよりもアセットを小さくしています。

このサンプル一式には、アプリケーションのバリデーションとリセット処理が含まれます。最後の状態を「ローカルでの確認」と呼ぶのは、登録も送信も行われないためです。「選択をクリア」は、選択内容とバリデーション履歴をリセットして最初の入力にフォーカスを移す、明示的な操作です。通常のフィールドエラーが起きても、自動では実行されません。

- base.cssには、色、スペーシング、タイポグラフィ、基準寸法が含まれます。

- checkboxとselection-groupのスタイルには、グループ化されたコントロールとインラインフィードバックが含まれます。

- notificationとbuttonのスタイルは、エラーサマリーの背景と操作ボタンに使用します。

関連する仕様を確認する

## Helsinki デザインシステムのサンプルで確認できること

### サービス機能を装わず、実装の詳細を示す

プレビューでは、実際のHDSコンポーネントのスタイル、キーボードフォーカス、修正、データ保持を1440、768、390pxの幅で確認できます。アクセシビリティを網羅的に監査したとするものではありません。実際の多言語対応の都市サービスには、ローカライズされたラベル、適切な言語メタデータ、サーバー側のルール、サービスバックエンドからの確認済み応答も必要です。

ソースコードはMITライセンスですが、独自の都市向けフォントには別個の権利上の制約があります。この独立した学習用サンプルでは架空のプログラムのテーマを使用しており、公式のHelsinkiのアイデンティティは一切使用していません。画面上の見た目やローカル状態を、実際のイベント登録と誤認しないでください。

関連する仕様を確認する

## Helsinkiデザインシステムのコンポーネント例

### ネイティブのグループ化されたチェックボックス構造

fieldsetとlegendで質問を示し、入力欄とラベルで複数の回答を表します。

```
<fieldset class="hds-selection-group" aria-describedby="topics-hint">
  <legend class="hds-selection-group__legend">Topics for your afternoon</legend>
  <p id="topics-hint">Choose at least two topics.</p>
  <div class="hds-selection-group__items hds-selection-group__items--vertical">
    <div class="hds-checkbox">
      <input class="hds-checkbox__input" type="checkbox" id="repair" value="Repair and reuse">
      <label class="hds-checkbox__label" for="repair">Repair and reuse</label>
    </div>
    <div class="hds-checkbox">
      <input class="hds-checkbox__input" type="checkbox" id="garden" value="Urban gardening">
      <label class="hds-checkbox__label" for="garden">Urban gardening</label>
    </div>
  </div>
</fieldset>
```

コードリファレンス

### エラーから修正までの選択フローを完全に実装

エラーサマリーへのフォーカス、修正箇所へのリンク、再確認、変更、選択のクリア。

```
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Plan a skills afternoon</title><link rel="stylesheet" href="vendor/hds-core-5.2.2/base.css"><link rel="stylesheet" href="vendor/hds-core-5.2.2/checkbox.css"><link rel="stylesheet" href="vendor/hds-core-5.2.2/selection-group.css"><link rel="stylesheet" href="vendor/hds-core-5.2.2/notification.css"><link rel="stylesheet" href="vendor/hds-core-5.2.2/button.css"><style>*{box-sizing:border-box}body{margin:0;padding:var(--spacing-layout-s) var(--spacing-s);font-family:var(--font-default);color:var(--color-black-90)}main{max-width:720px;margin:auto}h1{margin-top:8px}header{border-top:8px solid var(--color-copper);padding-top:var(--spacing-m)}.hds-selection-group{margin:24px 0}.hds-notification{margin:24px 0}.actions{display:flex;gap:16px;flex-wrap:wrap;margin-top:32px}footer{font-size:14px;line-height:1.5;margin-top:32px;border-top:1px solid var(--color-black-20);padding-top:16px}#review{background:var(--color-silver-light);padding:24px;margin-top:24px}[hidden]{display:none!important}@media(max-width:575px){.heading-xl{font-size:var(--fontsize-heading-xl-mobile)}}button{max-width:100%}</style><main class="text-body"><header><small>COMMUNITY SKILLS · LOCAL PLAN</small><h1 class="heading-xl">Plan a skills afternoon</h1><p>Select at least two topics for an example programme. Nothing is registered or sent.</p></header><form id="form" novalidate><div id="summary" class="hds-notification hds-notification--error" hidden><div class="hds-notification__content"><h2 id="summary-heading" class="hds-notification__label" tabindex="-1">Check your topic selection</h2><div class="hds-notification__body"><ul><li><a href="#repair" id="error-link">Choose at least two topics</a></li></ul></div></div></div><fieldset class="hds-selection-group" aria-describedby="hint field-error"><legend class="hds-selection-group__legend">Topics for your afternoon</legend><p id="hint">Choose two or more. You can change your selection before reviewing the plan.</p><div class="hds-selection-group__items hds-selection-group__items--vertical"><div class="hds-checkbox"><input id="repair" type="checkbox" class="hds-checkbox__input" value="Repair and reuse"><label class="hds-checkbox__label" for="repair">Repair and reuse</label></div><div class="hds-checkbox"><input id="digital" type="checkbox" class="hds-checkbox__input" value="Everyday digital skills"><label class="hds-checkbox__label" for="digital">Everyday digital skills</label></div><div class="hds-checkbox"><input id="garden" type="checkbox" class="hds-checkbox__input" value="Urban gardening"><label class="hds-checkbox__label" for="garden">Urban gardening</label></div></div><div id="field-error" class="hds-selection-group__error-text" hidden>Choose at least two topics.</div></fieldset><p id="count" role="status">0 topics selected.</p><div class="actions"><button class="hds-button hds-button--primary" type="submit">Review local plan</button><button id="reset" class="hds-button hds-button--secondary" type="button">Clear selection</button></div></form><section id="review" hidden tabindex="-1"><h2 class="heading-m">Your selected topics</h2><ul id="selected"></ul><p>This is a local review, not a booking confirmation.</p><button id="change" class="hds-button hds-button--secondary">Change topics</button></section><footer>Native HDS Core5.2.2 styles with Arial fallback. Original selection rule and local review. No Helsinki branding, registration or backend.</footer></main><script>let attempted=false;const boxes=[...document.querySelectorAll('input[type=checkbox]')];const values=()=>boxes.filter(x=>x.checked);function validate(focus=false){const n=values().length;document.querySelector('#count').textContent=n+' topics selected.';const bad=attempted&&n<2;document.querySelector('#summary').hidden=!bad;document.querySelector('#field-error').hidden=!bad;boxes.forEach(x=>{if(bad)x.setAttribute('aria-invalid','true');else x.removeAttribute('aria-invalid')});if(bad&&focus)document.querySelector('#summary-heading').focus();return !bad}boxes.forEach(x=>x.onchange=()=>validate());document.querySelector('#error-link').onclick=e=>{e.preventDefault();boxes[0].focus()};document.querySelector('#form').onsubmit=e=>{e.preventDefault();attempted=true;if(!validate(true))return;const list=document.querySelector('#selected');list.replaceChildren();values().forEach(x=>{const li=document.createElement('li');li.textContent=x.value;list.append(li)});document.querySelector('#form').hidden=true;document.querySelector('#review').hidden=false;document.querySelector('#review').focus()};document.querySelector('#change').onclick=()=>{document.querySelector('#form').hidden=false;document.querySelector('#review').hidden=true;boxes[0].focus()};document.querySelector('#reset').onclick=()=>{boxes.forEach(x=>x.checked=false);attempted=false;validate();boxes[0].focus()};</script></html>
```

コードリファレンス

## Helsinkiデザインシステムのエージェント設定

### 実装の出発点

Coreのアセットパスを正確に指定しています。アプリケーションコードがバリデーションと再確認を処理し、HelsinkiGroteskProは同梱されていません。Sourcesにある動作例のZIPには、プレビューに必要な依存関係とドキュメント一式も含まれています。ZIPを展開し、そのディレクトリでpython3 -m http.server 8080を実行してから、http://localhost:8080/helsinki.htmlを開いてください。モジュールを使うサンプルをfile://から直接開かないでください。

```
npm install hds-core@5.2.2
# CSS imports in a bundler:
# import 'hds-core/lib/base.css';
# import 'hds-core/lib/components/checkbox/checkbox.css';
# import 'hds-core/lib/components/selection-group/selection-group.css';
# import 'hds-core/lib/components/notification/notification.css';
# import 'hds-core/lib/components/button/button.css';
# In plain HTML, copy these files into public assets and link base.css first.
# HelsinkiGroteskPro is not bundled; the native font stack falls back to Arial.
```

### あなたのプロジェクト向けプロンプト

```
HDS Core5.2.2のベースと選択したコンポーネントCSSを使用します。関連するチェックボックスはfieldset/legendでグループ化し、ラベルとヒントを保持して、セマンティックなエラートークンを使用してください。再確認に失敗した場合は、フォーム見出しの下にリンク付きエラーを表示し、サマリーの見出しにフォーカスします。修正後に再確認し、選択済みの値を保持するとともに、ローカルでの再確認とサーバーが確認した送信を区別してください。
```

## Helsinkiデザインシステムの参照元と適用範囲

独立したOpenDesignのサンプルです。Helsinkiのフォントアセットやサービスのアイデンティティは使用していません。登録機能やバックエンドの結果もありません。

- Coreのセットアップ ベースとコンポーネントのCSSを分離し、フォントの著作権上の境界を明確化。

- フォームの構築 グループ化、コントロールの選択、フォーカス順。

- バリデーションのパターン サマリーの配置、リンク、修正、バックエンドとの境界。

- デザイントークン タイポグラフィ、間隔、色の役割。

- 公式リポジトリ パッケージの構成とMITライセンス。

- 動作サンプル一式をダウンロード 完全なHTML、ローカルのCSS／JavaScript依存関係、付属ライセンス、正確な起動手順を含むZIPです。ビルド手順は不要です。

## Helsinkiデザインシステムの関連リソース

### Rivet

Rivetの実際のトークンスケール、HTMLのコンポーネント構造、キーボード操作への標準対応を活用して、大学のページを作成します。アクセシブルな来場案内タブを備えた、コンパクトなワークショップ詳細ページをご覧ください。

### Digital Agency デザインシステム

DADSのテキストロール、セマンティックなトークン、ネイティブなHTMLコンポーネント構造を使って、読みやすい日本語の行政サービス向けインターフェースを構築できます。形式エラー、該当なしの結果、確認可能なステータス記録を備えた、動作する受付番号検索をお試しください。

### KERN

タイポグラフィ、セマンティックなテーマ、開閉パネル、元に戻せる確認フローを備えたネイティブなKERNインターフェースを構築します。


- [実装リファレンス](https://hds.hel.fi/patterns/forms/form-validation/)
- [ソース](https://github.com/City-of-Helsinki/helsinki-design-system/tree/development/packages/design-tokens)
- [ソース](https://hds.hel.fi/patterns/forms/form-building/)
- [関連する仕様を確認する](https://github.com/City-of-Helsinki/helsinki-design-system/blob/development/packages/core/README.md)
- [関連する仕様を確認する](https://github.com/City-of-Helsinki/helsinki-design-system/tree/development/packages/design-tokens)
- [コードリファレンス](https://hds.hel.fi/patterns/forms/form-building/)
- [関連する仕様を確認する](https://hds.hel.fi/patterns/forms/form-building/)
- [関連する仕様を確認する](https://hds.hel.fi/patterns/forms/form-validation/)
- [関連する仕様を確認する](https://github.com/City-of-Helsinki/helsinki-design-system)
- [コードリファレンス](https://hds.hel.fi/patterns/forms/form-validation/)
- [Coreのセットアップ ベースとコンポーネントのCSSを分離し、フォントの著作権上の境界を明確化。](https://github.com/City-of-Helsinki/helsinki-design-system/blob/development/packages/core/README.md)
- [フォームの構築 グループ化、コントロールの選択、フォーカス順。](https://hds.hel.fi/patterns/forms/form-building/)
- [バリデーションのパターン サマリーの配置、リンク、修正、バックエンドとの境界。](https://hds.hel.fi/patterns/forms/form-validation/)
- [デザイントークン タイポグラフィ、間隔、色の役割。](https://github.com/City-of-Helsinki/helsinki-design-system/tree/development/packages/design-tokens)
- [公式リポジトリ パッケージの構成とMITライセンス。](https://github.com/City-of-Helsinki/helsinki-design-system)