PackagesUIComponentsLayouts
Stack / HStack
垂直・水平方向のレイアウトコンポーネント。gapトークンで近接の原則を体系化する。
いつ使うか
- 要素を垂直または水平に並べるとき
- コンポーネント間のスペーシングを一貫させたいとき
gapトークンで近接の原則（関連する要素は近づける）を表現するとき
いつ使わないか
- CSS Grid が必要な2次元レイアウトには使わない
- 1つの要素しかない場合は不要である
Usage
import { HStack, Stack } from '@bi-shop-it/ui/stack';
<Stack>
<Heading>タイトル</Heading>
<Paragraph>本文テキスト</Paragraph>
</Stack>
<HStack>
<ActionButton label="キャンセル" variant="secondary" />
<ActionButton label="保存" />
</HStack>Props
Stack
| Prop | 型 | デフォルト | 説明 |
|---|---|---|---|
gap | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' | 子要素間の間隔 |
align | 'start' | 'center' | 'end' | 'stretch' | 'baseline' | 'stretch' | 交差軸方向の配置 |
wrap | boolean | false | 子要素の折り返しを有効にする |
asChild | boolean | false | 子要素をルート要素として使用する |
HStack
| Prop | 型 | デフォルト | 説明 |
|---|---|---|---|
gap | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' | 子要素間の間隔 |
align | 'start' | 'center' | 'end' | 'stretch' | 'baseline' | 'center' | 交差軸方向の配置 |
wrap | boolean | false | 子要素の折り返しを有効にする |
asChild | boolean | false | 子要素をルート要素として使用する |
gap の使い分け
近接の原則（Gestalt の法則）に基づき、関連度に応じた gap を選択する。
| gap | 値 | 用途 | 例 |
|---|---|---|---|
xs | 4px | 密接な要素 | ラベルと値、アイコンとテキスト |
sm | 8px | 同一グループ内の項目 | フォーム内のチェックボックス群 |
md | 16px | コンポーネント間の基本間隔 | フォームフィールド間、カード内要素 |
lg | 24px | セクション内の余白 | セクション内のブロック間 |
xl | 32px | セクション間の区切り | ページ内の大きなセクション間 |
状態
基本（Stack）
Item 1
Item 2
Item 3
<Stack>
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Stack>Gap 比較
xs (4px)
A
B
sm (8px)
A
B
md (16px)
A
B
lg (24px)
A
B
xl (32px)
A
B
<Stack gap="xs">...</Stack>
<Stack gap="sm">...</Stack>
<Stack gap="md">...</Stack>
<Stack gap="lg">...</Stack>
<Stack gap="xl">...</Stack>基本（HStack）
Item 1
Item 2
Item 3
<HStack>
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</HStack>Wrap（折り返し）
タグ1タグ2タグ3タグ4タグ5
<HStack gap="sm" wrap>
<Tag color="teal" label="タグ1" />
<Tag color="pink" label="タグ2" />
<Tag color="lime" label="タグ3" />
<Tag color="teal" label="タグ4" />
<Tag color="pink" label="タグ5" />
</HStack>Align バリエーション
start
A
B
center（デフォルト）
A
B
end
A
B
stretch
A
B
baseline
A
B
<HStack align="start">...</HStack>
<HStack align="center">...</HStack>
<HStack align="end">...</HStack>
<HStack align="stretch">...</HStack>
<HStack align="baseline">...</HStack>Spacer
Stack / HStack 内で残りのスペースを埋めて要素を押し出すユーティリティコンポーネント。flex-grow: 1 のみを持つ。
いつ使うか
- HStack 内でタイトルとアクションを左右に分離するとき
- Stack / HStack 内で要素を端に寄せたいとき
Usage
import { HStack, Spacer } from '@bi-shop-it/ui/stack';
<HStack>
<p>タイトル</p>
<Spacer />
<ActionButton label="アクション" />
</HStack>;Props
Props は受け付けない。装飾要素であるため aria-hidden="true" が内部で付与される。
デモ
Spacer なしでは要素が左に詰まるが、Spacer ありではボタンが右端に押し出される。
Spacer なし
タイトル
Spacer あり
タイトル
{
/* Spacer なし — 要素が左に詰まる */
}
<HStack>
<p>タイトル</p>
<ActionButton label="アクション" size="sm" />
</HStack>;
{
/* Spacer あり — ボタンが右端に押し出される */
}
<HStack>
<p>タイトル</p>
<Spacer />
<ActionButton label="アクション" size="sm" />
</HStack>;アクセシビリティ
コンポーネントが内部で処理すること
- レイアウト専用のコンポーネントであり、セマンティクスは付与しない（
divを使用する） asChildで任意のセマンティック要素（nav,section等）に差し替え可能である
利用者が対応すること
- ナビゲーション等のセマンティクスが必要な場合は
asChildで適切な要素を指定すること
関連コンポーネント
- スペーシングトークン — gap の値はスペーシングトークンの推奨値に基づく