patterns
UI State (idle/loading/success/error)
非同期処理の状態遷移を、見た目と責務で分離。NyanoやToolsで特に効く。
stateasynccss+js
Customize
--mk-state-hold-success / --mk-state-hold-error
A11y
状態の意味はテキストで伝え、色だけに依存しない。
Install
“壊れにくさ”優先のため、依存は増やさずに ファイルをコピーして使う 形式です。
Files
まずは下記ファイルをプロジェクトに配置してください。
required-files.md
- tailwind-motion-kit/css/00_tokens.css (css)
- tailwind-motion-kit/css/19_state.css (css)
- tailwind-motion-kit/js/state.js (js)Option A
まずは Bundle を読み込んで、動作を確認するのがおすすめです。
globals.css
/* Bundle: まずはこれが一番簡単 */
@import "./tailwind-motion-kit/css/99_bundle.css";Option B
必要な CSS だけ読み込みたい場合はこちら。
globals.css
/* 1) CSS: グローバルCSSに追記 */
@import "./tailwind-motion-kit/css/00_tokens.css";
@import "./tailwind-motion-kit/css/19_state.css";JavaScript
動きやUI制御が必要な場合のみ、初期化を追加します。
init.js
import { withUiState } from "./tailwind-motion-kit/js/state.js";
// withUiState(el, async () => { ... })Snippets
Copy & paste
usage.html
<button class="mk-state-inline-flex" data-mk-ui-state="idle" id="btn">
<span class="mk-when-idle">Send</span>
<span class="mk-when-loading">Loading...</span>
<span class="mk-when-success">Done</span>
<span class="mk-when-error">Error</span>
</button>usage.js
import { withUiState } from "./tailwind-motion-kit/js/state.js";
// withUiState(el, async () => { ... })Files
この部品が参照する実ファイルです。
tailwind-motion-kit/css/00_tokens.csscss
tailwind-motion-kit/css/00_tokens.css
/*!
* Tailwind Motion Kit (mk) - Tokens
* --------------------------------
* 目的: 速度・距離・イージング等の“モーション言語”を統一し、
* パーツを増やしても品位が崩れない状態を作ります。
*
* 使い方:
* - :root の変数を上書きするだけで全体の動きを一括調整できます。
* - 個別要素は style="" か data-mk-* 属性で上書きできます(JSがある場合)。
*/
:root {
/* --- イージング(加減速) --- */
--mk-ease-out: cubic-bezier(0.16, 1, 0.3, 1);
--mk-ease-in: cubic-bezier(0.32, 0, 0.67, 0);
--mk-ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
/* “少しだけ遊び”が欲しい時用(多用は上品さを損ねます) */
--mk-ease-out-back: cubic-bezier(0.34, 1.56, 0.64, 1);
/* --- 時間 --- */
--mk-duration-fast: 160ms;
--mk-duration-medium: 280ms;
--mk-duration-slow: 600ms;
--mk-duration-slower: 900ms;
/* コンポーネントが参照する“共通デフォルト” */
--mk-duration: var(--mk-duration-medium);
--mk-ease: var(--mk-ease-out);
--mk-delay: 0ms;
/* --- 移動量 --- */
--mk-distance-1: 6px;
--mk-distance-2: 12px;
--mk-distance-3: 20px;
--mk-distance: var(--mk-distance-2);
/* --- ぼかし --- */
--mk-blur-0: 0px;
--mk-blur-1: 6px;
--mk-blur-2: 10px;
--mk-blur: var(--mk-blur-1);
/* --- 影(浮遊感) --- */
--mk-shadow-lift: 0 12px 30px rgba(0, 0, 0, 0.14);
--mk-shadow-soft: 0 10px 22px rgba(0, 0, 0, 0.10);
/* --- アンダーライン --- */
--mk-underline-thickness: 2px;
--mk-underline-offset: 0.2em;
/* --- フォーカスリング --- */
--mk-ring-color: rgba(59, 130, 246, 0.35);
--mk-ring-size: 3px;
/* --- スケルトン(ロード中) --- */
--mk-skeleton-a: rgba(0, 0, 0, 0.06);
--mk-skeleton-b: rgba(0, 0, 0, 0.12);
--mk-skeleton-speed: 1250ms;
/* --- スピナー --- */
--mk-spinner-size: 1.2em;
--mk-spinner-border: 2px;
/* --- テキスト分割表示 --- */
--mk-char-step: 25ms; /* 1文字ごとの遅延 */
/* --- ダイアログ / ドロワー --- */
--mk-dialog-duration: var(--mk-duration-slow);
--mk-dialog-ease: var(--mk-ease-out);
--mk-dialog-backdrop-opacity: 0.45;
--mk-dialog-offset: var(--mk-distance-3);
--mk-dialog-scale-from: 0.995;
--mk-dialog-radius: 18px;
/* --- 折りたたみ(アコーディオン) --- */
--mk-collapse-duration: var(--mk-duration-medium);
--mk-collapse-ease: var(--mk-ease);
/* --- Toast / 通知 --- */
--mk-toast-gap: 10px;
--mk-toast-width: min(360px, calc(100vw - 24px));
--mk-toast-duration: var(--mk-duration-medium);
--mk-toast-ease: var(--mk-ease-out);
/* --- スクロール進捗(トップバー) --- */
--mk-scroll-progress-top: 0px;
--mk-scroll-progress-height: 3px;
--mk-scroll-progress-ease: linear;
/* --- ナビ下線インジケータ --- */
--mk-nav-underline-height: 2px;
--mk-nav-underline-radius: 999px;
--mk-nav-duration: var(--mk-duration-medium);
--mk-nav-ease: var(--mk-ease-out);
/* --- UI state(idle/loading/success/error) --- */
--mk-state-hold-success: 900ms;
--mk-state-hold-error: 1400ms;
/* --- Tabs --- */
--mk-tabs-gap: 10px;
--mk-tabs-radius: 999px;
--mk-tabs-duration: var(--mk-duration-medium);
--mk-tabs-ease: var(--mk-ease-out);
--mk-tabs-underline-height: 2px;
--mk-tabs-underline-color: currentColor;
/* --- Tooltip --- */
--mk-tooltip-bg: rgba(0, 0, 0, 0.82);
--mk-tooltip-fg: #fff;
--mk-tooltip-radius: 10px;
--mk-tooltip-padding: 10px 12px;
--mk-tooltip-gap: 8px;
--mk-tooltip-shadow: 0 18px 60px rgba(0,0,0,0.35);
--mk-tooltip-max-width: 260px;
/* --- Stepper --- */
--mk-stepper-gap: 14px;
--mk-step-size: 28px;
--mk-step-line: rgba(255, 255, 255, 0.14);
--mk-step-done: rgba(59, 130, 246, 1);
--mk-step-current: rgba(255, 255, 255, 0.92);
--mk-step-todo: rgba(255, 255, 255, 0.5);
}
/* motion減衰設定のあるユーザーには、動きを最小化して“結果”を出します */
@media (prefers-reduced-motion: reduce) {
:root {
--mk-duration-fast: 0ms;
--mk-duration-medium: 0ms;
--mk-duration-slow: 0ms;
--mk-duration-slower: 0ms;
--mk-duration: 0ms;
--mk-delay: 0ms;
}
}
tailwind-motion-kit/css/19_state.csscss
tailwind-motion-kit/css/19_state.css
/*!
* Tailwind Motion Kit (mk) - UI State (idle/loading/success/error)
* ---------------------------------------------------------------
* 目的: data属性1つで “状態ごとの表示” を切り替えます。
* Nyano の「接続 / 承認 / 実行 / 完了 / 失敗」などに便利です。
*
* 例:
* <button class="mk-state-inline-flex" data-mk-ui-state="idle">
* <span class="mk-when-idle">Mint</span>
* <span class="mk-when-loading"><span class="mk-spinner"></span> Processing</span>
* <span class="mk-when-success">Done</span>
* <span class="mk-when-error">Try again</span>
* </button>
*
* JS:
* import { setUiState, withUiState } from "./js/state.js";
*/
[data-mk-ui-state] .mk-when-idle,
[data-mk-ui-state] .mk-when-loading,
[data-mk-ui-state] .mk-when-success,
[data-mk-ui-state] .mk-when-error {
display: none;
}
[data-mk-ui-state="idle"] .mk-when-idle { display: var(--mk-when-display, inline); }
[data-mk-ui-state="loading"] .mk-when-loading { display: var(--mk-when-display, inline); }
[data-mk-ui-state="success"] .mk-when-success { display: var(--mk-when-display, inline); }
[data-mk-ui-state="error"] .mk-when-error { display: var(--mk-when-display, inline); }
.mk-state-block { --mk-when-display: block; }
.mk-state-inline { --mk-when-display: inline; }
.mk-state-inline-flex { --mk-when-display: inline-flex; }
tailwind-motion-kit/js/state.jsjs
tailwind-motion-kit/js/state.js
// Tailwind Motion Kit (mk) - UI State
// ----------------------------------
// data-mk-ui-state="idle|loading|success|error" を操作する小さなヘルパー。
// “状態遷移”の見通しを良くし、UIの品質を上げます。
function toMs(value, fallbackMs) {
if (value == null || value === "") return fallbackMs;
const v = String(value).trim();
if (v.endsWith("ms")) return Number(v.replace("ms", "")) || fallbackMs;
if (v.endsWith("s")) return (Number(v.replace("s", "")) * 1000) || fallbackMs;
const n = Number(v);
return Number.isFinite(n) ? n : fallbackMs;
}
export function setUiState(el, state) {
if (!el) return;
el.setAttribute("data-mk-ui-state", state);
if (state === "loading") el.setAttribute("aria-busy", "true");
else el.removeAttribute("aria-busy");
}
export async function withUiState(el, task, {
idle = "idle",
loading = "loading",
success = "success",
error = "error",
successHold = null,
errorHold = null,
} = {}) {
if (!el) {
// element が無いなら、ただ実行
return typeof task === "function" ? await task() : await task;
}
// :root token を使いたい場合のデフォルト
if (successHold == null) {
const v = getComputedStyle(document.documentElement).getPropertyValue("--mk-state-hold-success");
successHold = toMs(v, 900);
}
if (errorHold == null) {
const v = getComputedStyle(document.documentElement).getPropertyValue("--mk-state-hold-error");
errorHold = toMs(v, 1400);
}
setUiState(el, loading);
try {
const res = typeof task === "function" ? await task() : await task;
setUiState(el, success);
if (successHold != null && successHold > 0) await new Promise((r) => setTimeout(r, successHold));
setUiState(el, idle);
return res;
} catch (err) {
setUiState(el, error);
if (errorHold != null && errorHold > 0) await new Promise((r) => setTimeout(r, errorHold));
setUiState(el, idle);
throw err;
}
}
Preview
UI state(idle / loading / success / error)
状態は data-mk-ui-state の1つで切り替えられます。
Tips
- • デザイン側は CSS 変数(tokens)で一括調整できます。
- • 動きは “短く・小さく・同じ癖” を優先すると品位が保てます。
- • prefers-reduced-motion を必ず考慮してください。
