Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/design-principles/principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,7 @@

- アイコンの描き方(線か塗りか)をサイト内で揃える。
- 日付、金額、状態の表記を揃える。
- トップページの機能一覧(主なページへの入口)とナビゲーションの項目は、一つの定義から作る。別々に書くと、片方にだけ載ってたどり着けない画面ができる。

**出典**: 一貫性、ニールセン「一貫性と標準化」、ジャコブの法則、情報提示の原則「内部一貫性及び外部一貫性を保つ」

Expand All @@ -212,6 +213,7 @@
- [ ] 色の意味が画面ごとに変わっていないか
- [ ] ナビゲーションの位置と順序が全ページで同じか
- [ ] 広く使われている配置を外す箇所に、外す理由があるか
- [ ] ナビゲーションに載っている画面が、トップページの機能一覧からもたどれるか

**トークン**: 意味ごとの色、ボタンのバリアント、ナビゲーションの部品。

Expand All @@ -231,6 +233,9 @@
**推奨**

- 400 ミリ秒を超える処理は、完了を待たせず進捗を見せる。
- 保存、更新、削除が済んだら、結果を一文で画面の上部に出す(「『週次レポート』を保存しました。」)。時間で消さず、利用者が閉じるか次の作成や編集を始めるまで残す。中断(キャンセル)では出さない。
- 一覧から作成や編集に入ったら、一覧の代わりに編集の画面だけを出し、何を作るか、どれを直しているかを見出しにする(「『週次レポート』を編集」)。見出しへフォーカスを移す。一覧の上に編集の欄を重ねて出すと、どの項目を直しているか分からなくなる。
- 作成や編集を終えて一覧に戻ったら、結果の表示が見える位置(ページの先頭)へスクロールを戻す。

**出典**: ニールセン「システム状態の可視化」、ドハティのしきい値、対話の原則「自己記述性」

Expand All @@ -239,6 +244,7 @@
- [ ] 処理中であることが分かるか
- [ ] 操作が受け付けられたことが分かるか
- [ ] 現在のページ位置が分かるか
- [ ] 保存や削除のあと、済んだことが読み終える前に消えていないか
- [ ] 自動で動く要素を止められるか

**トークン**: 進捗、トースト、スケルトン、現在地を示すナビゲーションの状態。
Expand Down
1 change: 1 addition & 0 deletions docs/improvement/log.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
| 2026-11-07 | 部品 | 利用側が `style-src` に `'unsafe-inline'` を入れない CSP を掛けると、サーバーで描画した `style` 属性が止まり、Checkbox・Radio・Switch の隣のネイティブ入力が見えていた。`hide-native-input` でクラスからも隠し、Skeleton の既定の大きさをクラスに移した。ルールブック 04 に「CSP の下で使う」(Base UI が出す style、ハッシュでの許し方、eval を使わない検証ライブラリ)を追加。bouzu(#78・#82・#84)での知見 | Checkbox・Switch・Skeleton のテスト。ルールブック 04 に style 属性に頼らない規約を追加 |
| 2026-11-07 | 部品 | AlertDialog を追加(バックログ)。取り消せない操作の前の確認に使う。見出しは対象を入れた問いかけ、ボタンは「キャンセル」と動詞。開くとフォーカスをキャンセルに置き、`onConfirm` が Promise なら終わるまで処理中にして閉じない。bouzu(#73)の削除確認の文言と流れから | 単体テスト(名前・説明・初期フォーカス・キャンセル・処理中・失敗・外側を押しても閉じない)とストーリーの play 関数。04 の部品の選び方に追加 |
| 2026-11-07 | 部品 | SortableList を追加。つまみのドラッグ(行が指に付いて動き、離した位置へ一度で動く)と矢印キーで並べ替え、右の開閉ボタンから「上へ」「下へ」「外す」を出す。並びが変わると FLIP で動かし、動かした位置を読み上げる。bouzu(#77・#89)の読誦セットの並べ替えを部品にした | 単体テスト(矢印キーとフォーカスの維持・開閉の操作・外したあとのフォーカス・ドラッグ・文言の上書き)と、位置の計算の純粋な関数のテスト。ストーリーの play 関数 |
| 2026-11-07 | 文書 | bouzu(#73・#80・#81)で直した画面の流れを原則に足した。「状態と応答」の推奨に完了の知らせ(時間で消さない・キャンセルでは出さない)、編集中は一覧の代わりに編集の画面だけを出して見出しへフォーカスを移すこと、戻ったら先頭へスクロールすること。「一貫性」の推奨に機能一覧とナビゲーションを一つの定義から作ること。05 文言にボタンの語彙の表と、確認・完了・空の一覧の書き方 | 原則のレビュー項目に 2 つ追加(design-review で確認される) |
| 2026-11-02 | 保守 | Node.js を 26.13.0(LTS Lithium)に更新。`devEngines` を `>=26.13.0`、`@types/node` を 26 系(`^26.6.6`)に合わせた。他の依存の版は変えていない | ADR-0020。CI は `.tool-versions` の版を使う |
| 2026-10-23 | 保守 | 全体のリファクタリング。古い参照(存在しない make ターゲット・パス・README の節名)を直し、トークンを変えた後の手順を `make generate` に統一。Makefile と重複していた pnpm スクリプト、design-review に混ざっていたコードレビュー・Next.js の項目、使われていない関数と export を削除。DESIGN.md・ルールブック 04・06・CONTRIBUTING・factory.md の重複を正本へのリンクにし、トークンの CSS 化の規則を `packages/tokens/scripts/lib/css.ts` に集めて build.ts とスライドで共有 | 規則を 1 か所にしたので、tokens.css とスライドの値の書き方がずれない。重複していた手順は正本(Makefile・COMPONENT_STRUCTURE.md・06 章・ds-factory)だけに置いた |
| 2026-10-23 | 機能 | 8341-ui を使うプロダクトに、DESIGN.md と design-principles を配るレジストリ item `@8341/design-md` を追加。DESIGN.md はコードから読み取れない考え方(プロダクトの前提・画面領域ごとの方向性・大事にすること・外した必須)と原則の必須の要約だけにし、トークンや部品の一覧は載せない | ADR-0019。原則の要約は `scripts/sync-product-design.ts` が docs/design-principles から生成し、`make check` で鮮度を検査。配布する原則のファイル一覧も registry.json の --check で追従 |
Expand Down
22 changes: 22 additions & 0 deletions docs/rulebook/05-writing.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,28 @@ design-principles の原則「文言」「誤りと撤回」「一貫性」の
- ✅ 申請する / 下書きを保存する / 削除する
- ❌ OK / 実行 / 次へ(何が起きるか分からない場合)
- 破壊的な操作は対象を書く: 「このファイルを削除する」
- 同じ機能には全画面で同じ語を使う。和語の言い換え(直す・消す・やめる・加える)を画面ごとに混ぜない

| 機能 | 一覧の行に並べるボタン | 確定するボタン |
| --- | --- | --- |
| 作る | 「新しい○○を作る」(一覧の見出しの横) | 「保存する」 |
| 直す | 「編集」 | 「保存する」 |
| 消す | 「削除」 | 「削除する」(AlertDialog か、行の中の確認) |
| やめる | — | 「キャンセル」 |
| 一覧から外す(項目そのものは消えない) | 「外す」 | — |

- 一覧の行に同じボタンが並ぶときは、見える文字は短くし、読み上げの名前に対象を入れる(`aria-label="週次レポートを編集"`)

## 確認と完了の知らせ

| 場面 | 書き方 | 例 |
| --- | --- | --- |
| 取り消せない操作の確認(見出し) | 「『対象』を〜しますか」 | 「週次レポート」を削除しますか |
| 確認の説明 | 結果だけを書く | 元に戻せません。 |
| 完了の知らせ(NotificationBanner の success、`live`) | 「『対象』を〜しました。」 | 「週次レポート」を保存しました。 |
| 空の一覧 | 無いことと、次にすること | まだレポートがありません。「新しいレポートを作る」から作成してください。 |

保存と更新で語を分ける(新しく作ったら「保存しました」、直したら「更新しました」)。時間で消える通知にせず、閉じるボタンで消す(design-principles の「状態と応答」)。

## リンク

Expand Down
Loading