UI スタイル
@vizejs/ui は、アクセシブルな振る舞いとビジュアルデザインを分離しています。CSS なしで始める、用意されたスタイルを追加する、同じセマンティック属性を自分のデザインシステムから使う、という選択ができます。Tailwind は必須でも特別扱いでもありません。
3 つの import から始める
共有トークン、1 つのプリセット、この画面で使うコンポーネントのスタイルだけを読み込みます。
import "@vizejs/ui/base.css";
import "@vizejs/ui/theme-preset-paper.css";
import "@vizejs/ui/component-button.css";
<script setup lang="ts">
import { Button } from "@vizejs/ui/button";
</script>
<template>
<main data-vize-theme="paper">
<Button type="button" variant="solid" tone="accent">変更を保存</Button>
<Button type="button" variant="outline" tone="neutral">プレビュー</Button>
<Button type="button" variant="quiet" tone="danger">削除</Button>
</main>
</template>
すべてのルートで共有する CSS はアプリケーションのエントリーから読み込んでください。コンポーネントの import が、テーマや別のコンポーネントのビジュアルルールを暗黙に追加することはありません。
パレットではなく、デザインの声を選ぶ
各プリセットは、配色だけでなく形状、タイポグラフィ、奥行き、密度、モーションまで異なります。型付き Props とセマンティックな DOM 契約はすべて共通です。
| プリセット | デザインの方向性 | 最初の選択に向く用途 |
|---|---|---|
atelier |
静かなニュートラル、柔らかな形状、抑制した奥行き | 生産性ツール、編集ツール |
paper |
温かいインク、細い罫線、角張った操作部、ほぼ浮かない表現 | 出版、情報密度の高い UI |
signal |
コンパクトなグラファイト、鋭い輪郭、等幅書体、浅い奥行き | 運用画面、開発者ツール |
midnight |
暗い発光面と、制御されたレイヤー状の影 | メディア、集中用ワークスペース |
play |
丸い形状、弾むような奥行き、表情のある押下フィードバック | ソーシャル、コンシューマー製品 |
high-contrast |
厳格な形状、強い状態分離、装飾的な奥行きなし | 状態の判別しやすさを最優先する UI |
headless |
固有の見た目を持たないセマンティックトークン境界 | 完全に独自のデザインシステム |
1 つのプリセット import で製品の声を固定できます。利用者が切り替えられる製品では、複数を読み込みます。
import "@vizejs/ui/theme-preset-atelier.css";
import "@vizejs/ui/theme-preset-midnight.css";
import "@vizejs/ui/theme-preset-paper.css";
document.documentElement.dataset.vizeTheme = "midnight";
各スタイルシートは、一致する data-vize-theme の範囲でだけ有効です。Shadow DOM ホストを含む、テーマの入れ子にも対応します。
<template>
<main data-vize-theme="atelier">
<EditorWorkspace />
<aside data-vize-theme="signal">
<OperationsPanel />
</aside>
</main>
</template>
Dialog や Tooltip などが document.body に Teleport される場合は、<html> にテーマを設定します。保存済みの設定を初回描画より前に適用する場合は @vizejs/ui/theme-scope を使います。
公開カスタムプロパティで調整する
ビジュアル CSS は data-vize-ui から始まり、その内側に型付き状態をネストします。追従が必要な BEM クラスや、生成されたユーティリティ文字列はありません。
.checkout-actions {
--vize-ui-button-radius: 0.5rem;
--vize-ui-button-shadow: none;
--vize-ui-button-shadow-hover: none;
--vize-ui-button-hover-lift: 0px;
--vize-ui-button-press-depth: 1px;
[data-vize-ui="button"] {
letter-spacing: 0.01em;
&[data-tone="danger"] {
--vize-ui-button-fill: var(--checkout-danger);
}
}
}
Button が公開するコンポーネントプロパティは次のとおりです。
| プロパティ | 用途 |
|---|---|
--vize-ui-button-fill |
塗りとアウトラインの色源 |
--vize-ui-button-ink |
塗りの上の前景色 |
--vize-ui-button-radius |
コントロールの形状 |
--vize-ui-button-shadow |
通常時の奥行き |
--vize-ui-button-shadow-hover |
ホバー時の奥行き |
--vize-ui-button-hover-lift |
ホバー時の移動量 |
--vize-ui-button-press-depth |
押下時の移動量 |
--vize-ui-button-press-scale |
押下時の縮尺 |
--vize-ui-button-hover-strength |
塗りつぶしのホバー色の混合率 |
--vize-ui-button-tint-strength |
outline と quiet のホバー色の混合率 |
Vize のカスケードレイヤー外にあるアプリケーション CSS は通常どおり優先されます。CSS Modules、scoped style、Tailwind、UnoCSS、グローバル CSS のどれからでも、コンポーネントを変えずに同じ契約を利用できます。
パッケージのソースはネイティブ CSS Nesting で記述されています。ビルド時に Lightning CSS が対象ブラウザー向けへ変換するため、アプリケーションは通常の CSS を受け取り、Vize のツールチェーンを必要としません。
アクセシビリティのポリシーを保つ
vize.policy レイヤーはビジュアルプリセットより後に置かれ、次の操作要件を守ります。
:focus-visibleでキーボードフォーカスを見える状態に保つ- 粗いポインターでは最小 44 CSS ピクセルの操作領域を確保する
prefers-reduced-motionでは装飾的な動きとローディングの回転を止める- forced-colors では背景、境界、文字、フォーカス、無効状態をシステム色へ対応させる
- ホバー専用フィードバックは、実際にホバーできる端末でだけ動かす
このポリシーを上書きする場合は、同等の操作性を保ってください。色のコントラスト、アクセシブルな名前、正確なローディング文言は、引き続きアプリケーション側の責任です。
ルートで使う分だけ読み込む
よく使うビジュアルアセットは独立して公開されています。
import "@vizejs/ui/component-input.css";
import "@vizejs/ui/component-checkbox.css";
import "@vizejs/ui/component-switch.css";
import "@vizejs/ui/component-tabs.css";
import "@vizejs/ui/component-dialog.css";
import "@vizejs/ui/component-card.css";
import "@vizejs/ui/component-alert.css";
import "@vizejs/ui/component-tooltip.css";
Input、Textarea、Checkbox、Switch、Button、Dialog、Card、Badge、Alert、Tooltip、Tabs、Breadcrumb、Pagination、Stepper は、それぞれコンポーネント単位のアセットを持ちます。ProgressBar と ScrollArea にも、低レベルで明示的に使うための CSS-only アセットがあります。同じスタイルを含む単体アセットとレガシーの集約エントリーを同時に読み込まないでください。
style.css はベースと従来のプリセットを含む互換用の集約ファイルです。新しいコードでは明示的な import を推奨します。style.css と base.css は併用しないでください。
フレームワークとレンダラー
ビジュアル層は静的 CSS です。setup コードを実行せず、ブラウザー API を読み取らず、サーバーのマークアップも変更しません。
- Nuxt では CSS エクスポートを
nuxt.config.tsのcssに追加するか、アプリケーションのエントリーから import します。Nuxtを参照してください。 - Void ではページまたはアプリケーションのエントリーから import し、ルートの CSS グラフに含めます。Voidを参照してください。
- DOM、SSR、ハイドレーション、Vapor は同じセマンティック属性を使います。Vapor 専用のスタイルシートは不要です。Vaporを参照してください。
次はコンポーネントカタログを開いてください。各リファレンスページには、操作できる使用例、コピー可能な SFC、型付き API、設計ガイド、規範的な振る舞い表、宣言済みの品質ゲートがあります。