⚠️ 重要提醒：
- 更多 AI ≠ 更好的 UX
- 過度自動化會降低使用者控制感
- 找到「最佳平衡點」是關鍵

傳統阻塞式 UI:
使用者輸入 → 等待 5-40 秒 → 一次顯示完整回應 ❌

串流式 UI:
使用者輸入 → 即時逐字顯示 → 持續更新直到完成 ✅

// 平滑串流文字動畫
const CHAR_DELAY = 5; // 5ms/字元 = 200 字元/秒

const StreamingText = ({ content }: { content: string }) => {
    const [displayedText, setDisplayedText] = useState('');
    const [currentIndex, setCurrentIndex] = useState(0);

    useEffect(() => {
        if (currentIndex < content.length) {
            const timer = setTimeout(() => {
                setDisplayedText(prev => prev + content[currentIndex]);
                setCurrentIndex(prev => prev + 1);
            }, CHAR_DELAY);
            return () => clearTimeout(timer);
        }
    }, [currentIndex, content]);

    return <div className="whitespace-pre-wrap">{displayedText}</div>;
};

import { useChat } from 'ai/react';

function ChatComponent() {
    const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();

    return (
        <div className="flex flex-col h-full">
            {/* 訊息列表 */}
            <div className="flex-1 overflow-y-auto">
                {messages.map((message) => (
                    <div
                        key={message.id}
                        className={`p-4 ${
                            message.role === 'user'
                                ? 'bg-blue-100 ml-auto'
                                : 'bg-gray-100'
                        }`}
                    >
                        {message.content}
                    </div>
                ))}
            </div>

            {/* 輸入區域 */}
            <form onSubmit={handleSubmit} className="p-4 border-t">
                <input
                    value={input}
                    onChange={handleInputChange}
                    disabled={isLoading}
                    placeholder="輸入訊息..."
                    className="w-full p-2 border rounded"
                />
            </form>
        </div>
    );
}

1. Processing (處理中)
   └── AI 接收並理解請求，尚無輸出

2. Generation (生成中)
   └── AI 開始產生回應，可串流顯示

// 基本骨架元件
const Skeleton = ({ className }: { className?: string }) => (
    <div
        className={`animate-pulse bg-gray-200 rounded ${className}`}
    />
);

// AI 回應骨架
const AIResponseSkeleton = () => (
    <div className="space-y-3 p-4">
        <Skeleton className="h-4 w-3/4" />
        <Skeleton className="h-4 w-full" />
        <Skeleton className="h-4 w-5/6" />
        <Skeleton className="h-4 w-2/3" />
    </div>
);

/* Shimmer 動畫 */
@keyframes shimmer {
    0% {
        background-position: -200% 0;
    }
    100% {
        background-position: 200% 0;
    }
}

.shimmer {
    background: linear-gradient(
        90deg,
        #f0f0f0 25%,
        #e0e0e0 50%,
        #f0f0f0 75%
    );
    background-size: 200% 100%;
    animation: shimmer 1.5s infinite;
}

// React Shimmer 元件
const ShimmerSkeleton = ({ className }: { className?: string }) => (
    <div
        className={`
            bg-gradient-to-r from-gray-200 via-gray-100 to-gray-200
            bg-[length:200%_100%]
            animate-[shimmer_1.5s_infinite]
            rounded
            ${className}
        `}
    />
);

// 三點跳動動畫
const TypingIndicator = () => (
    <div className="flex items-center space-x-1 p-3 bg-gray-100 rounded-lg w-fit">
        <span className="w-2 h-2 bg-gray-400 rounded-full animate-bounce"
              style={{ animationDelay: '0ms' }} />
        <span className="w-2 h-2 bg-gray-400 rounded-full animate-bounce"
              style={{ animationDelay: '150ms' }} />
        <span className="w-2 h-2 bg-gray-400 rounded-full animate-bounce"
              style={{ animationDelay: '300ms' }} />
    </div>
);

// 帶文字的指示器
const TypingIndicatorWithText = ({ name = 'AI' }: { name?: string }) => (
    <div className="flex items-center space-x-2 text-gray-500 text-sm">
        <TypingIndicator />
        <span>{name} is typing...</span>
    </div>
);

interface MessageProps {
    role: 'user' | 'assistant';
    content: string;
    timestamp?: Date;
}

const MessageBubble = ({ role, content, timestamp }: MessageProps) => {
    const isUser = role === 'user';

    return (
        <div className={`flex ${isUser ? 'justify-end' : 'justify-start'} mb-4`}>
            {/* AI 頭像 */}
            {!isUser && (
                <div className="w-8 h-8 rounded-full bg-purple-500 flex items-center justify-center mr-2">
                    <span className="text-white text-sm">AI</span>
                </div>
            )}

            <div className={`max-w-[70%] ${isUser ? 'order-1' : ''}`}>
                <div
                    className={`
                        px-4 py-2 rounded-2xl
                        ${isUser
                            ? 'bg-blue-500 text-white rounded-br-md'
                            : 'bg-gray-100 text-gray-900 rounded-bl-md'
                        }
                    `}
                >
                    {content}
                </div>

                {timestamp && (
                    <span className="text-xs text-gray-400 mt-1 block">
                        {timestamp.toLocaleTimeString()}
                    </span>
                )}
            </div>
        </div>
    );
};

interface QuickReply {
    label: string;
    value: string;
}

const QuickReplies = ({
    options,
    onSelect
}: {
    options: QuickReply[];
    onSelect: (value: string) => void;
}) => (
    <div className="flex flex-wrap gap-2 mt-3">
        {options.map((option) => (
            <button
                key={option.value}
                onClick={() => onSelect(option.value)}
                className="
                    px-4 py-2
                    border border-blue-500
                    text-blue-500
                    rounded-full
                    hover:bg-blue-50
                    transition-colors
                    text-sm
                "
            >
                {option.label}
            </button>
        ))}
    </div>
);

// 使用範例
<QuickReplies
    options={[
        { label: '查看訂單', value: 'view_orders' },
        { label: '聯繫客服', value: 'contact_support' },
        { label: '常見問題', value: 'faq' }
    ]}
    onSelect={handleQuickReply}
/>

type UserLevel = 'beginner' | 'intermediate' | 'expert';

const AdaptiveToolbar = ({ userLevel }: { userLevel: UserLevel }) => {
    const tools = {
        beginner: ['undo', 'redo', 'save'],
        intermediate: ['undo', 'redo', 'save', 'export', 'share'],
        expert: ['undo', 'redo', 'save', 'export', 'share', 'settings', 'plugins', 'api']
    };

    return (
        <div className="flex gap-2 p-2 bg-gray-100 rounded">
            {tools[userLevel].map((tool) => (
                <button key={tool} className="p-2 hover:bg-gray-200 rounded">
                    {tool}
                </button>
            ))}
        </div>
    );
};

const useAdaptiveTheme = () => {
    const [theme, setTheme] = useState<'light' | 'dark'>('light');

    useEffect(() => {
        const hour = new Date().getHours();
        // 晚上 7 點到早上 7 點自動切換深色模式
        const shouldBeDark = hour >= 19 || hour < 7;

        // 也可以偵測系統設定
        const systemPrefersDark = window.matchMedia(
            '(prefers-color-scheme: dark)'
        ).matches;

        setTheme(shouldBeDark || systemPrefersDark ? 'dark' : 'light');
    }, []);

    return theme;
};

// AI 根據使用者需求動態生成介面
const GenerativeUI = ({ userIntent }: { userIntent: string }) => {
    const [uiComponents, setUiComponents] = useState<React.ReactNode[]>([]);

    useEffect(() => {
        // 根據意圖生成對應的 UI 元件
        switch (userIntent) {
            case 'view_summary':
                setUiComponents([
                    <SummaryCard key="summary" />,
                    <QuickActions key="actions" />
                ]);
                break;
            case 'detailed_analysis':
                setUiComponents([
                    <DataTable key="table" />,
                    <Charts key="charts" />,
                    <ExportOptions key="export" />
                ]);
                break;
            default:
                setUiComponents([<DefaultView key="default" />]);
        }
    }, [userIntent]);

    return <div className="space-y-4">{uiComponents}</div>;
};

// ThemeContext.tsx
import { createContext, useContext, useState, useEffect } from 'react';

type Theme = 'light' | 'dark' | 'system';

interface ThemeContextType {
    theme: Theme;
    actualTheme: 'light' | 'dark';
    setTheme: (theme: Theme) => void;
}

const ThemeContext = createContext<ThemeContextType | null>(null);

export const ThemeProvider = ({ children }: { children: React.ReactNode }) => {
    const [theme, setTheme] = useState<Theme>(() => {
        return (localStorage.getItem('theme') as Theme) || 'system';
    });

    const [actualTheme, setActualTheme] = useState<'light' | 'dark'>('light');

    useEffect(() => {
        const updateActualTheme = () => {
            if (theme === 'system') {
                const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
                setActualTheme(systemDark ? 'dark' : 'light');
            } else {
                setActualTheme(theme);
            }
        };

        updateActualTheme();

        // 監聽系統主題變化
        const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
        mediaQuery.addEventListener('change', updateActualTheme);

        return () => mediaQuery.removeEventListener('change', updateActualTheme);
    }, [theme]);

    useEffect(() => {
        localStorage.setItem('theme', theme);
        document.documentElement.classList.toggle('dark', actualTheme === 'dark');
    }, [theme, actualTheme]);

    return (
        <ThemeContext.Provider value={{ theme, actualTheme, setTheme }}>
            {children}
        </ThemeContext.Provider>
    );
};

export const useTheme = () => {
    const context = useContext(ThemeContext);
    if (!context) throw new Error('useTheme must be used within ThemeProvider');
    return context;
};

import { Sun, Moon, Monitor } from 'lucide-react';

const ThemeToggle = () => {
    const { theme, setTheme } = useTheme();

    const options = [
        { value: 'light', icon: Sun, label: '淺色' },
        { value: 'dark', icon: Moon, label: '深色' },
        { value: 'system', icon: Monitor, label: '系統' }
    ] as const;

    return (
        <div className="flex bg-gray-100 dark:bg-gray-800 rounded-lg p-1">
            {options.map(({ value, icon: Icon, label }) => (
                <button
                    key={value}
                    onClick={() => setTheme(value)}
                    className={`
                        flex items-center gap-2 px-3 py-2 rounded-md text-sm
                        transition-colors
                        ${theme === value
                            ? 'bg-white dark:bg-gray-700 shadow'
                            : 'hover:bg-gray-200 dark:hover:bg-gray-700'
                        }
                    `}
                    aria-label={label}
                >
                    <Icon className="w-4 h-4" />
                    <span className="hidden sm:inline">{label}</span>
                </button>
            ))}
        </div>
    );
};

// tailwind.config.js
module.exports = {
    darkMode: 'class', // 或 'media' 自動跟隨系統
    theme: {
        extend: {
            colors: {
                // 深色模式專用色彩
                dark: {
                    bg: '#121212',      // 避免純黑
                    surface: '#1E1E1E',
                    elevated: '#2D2D2D',
                    border: '#3D3D3D'
                }
            }
        }
    }
}

// 支援螢幕閱讀器的 AI 回應
const AccessibleAIResponse = ({
    content,
    isLoading
}: {
    content: string;
    isLoading: boolean;
}) => (
    <div
        role="region"
        aria-label="AI 回應"
        aria-live="polite"
        aria-busy={isLoading}
    >
        {isLoading ? (
            <span aria-label="AI 正在思考中">
                <TypingIndicator />
            </span>
        ) : (
            <div>{content}</div>
        )}
    </div>
);

// 尊重使用者的動畫偏好設定
const useReducedMotion = () => {
    const [prefersReducedMotion, setPrefersReducedMotion] = useState(false);

    useEffect(() => {
        const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
        setPrefersReducedMotion(mediaQuery.matches);

        const handler = (e: MediaQueryListEvent) => setPrefersReducedMotion(e.matches);
        mediaQuery.addEventListener('change', handler);
        return () => mediaQuery.removeEventListener('change', handler);
    }, []);

    return prefersReducedMotion;
};

// 使用
const AnimatedComponent = () => {
    const reducedMotion = useReducedMotion();

    return (
        <div
            className={reducedMotion ? '' : 'animate-bounce'}
        >
            {/* 內容 */}
        </div>
    );
};

interface AIErrorProps {
    type: 'timeout' | 'rate_limit' | 'server_error' | 'content_filter';
    onRetry?: () => void;
}

const AIErrorMessage = ({ type, onRetry }: AIErrorProps) => {
    const errorConfig = {
        timeout: {
            icon: '⏱️',
            title: '回應逾時',
            message: 'AI 回應時間過長，請稍後再試',
            canRetry: true
        },
        rate_limit: {
            icon: '🚫',
            title: '請求過於頻繁',
            message: '請稍等一下再發送新的請求',
            canRetry: false
        },
        server_error: {
            icon: '⚠️',
            title: '服務暫時無法使用',
            message: '我們正在處理這個問題，請稍後再試',
            canRetry: true
        },
        content_filter: {
            icon: '🛡️',
            title: '內容無法處理',
            message: '您的請求包含無法處理的內容，請修改後重試',
            canRetry: false
        }
    };

    const config = errorConfig[type];

    return (
        <div className="bg-red-50 border border-red-200 rounded-lg p-4">
            <div className="flex items-start gap-3">
                <span className="text-2xl">{config.icon}</span>
                <div className="flex-1">
                    <h4 className="font-medium text-red-800">{config.title}</h4>
                    <p className="text-red-600 text-sm mt-1">{config.message}</p>

                    {config.canRetry && onRetry && (
                        <button
                            onClick={onRetry}
                            className="mt-3 px-4 py-2 bg-red-100 hover:bg-red-200
                                       text-red-700 rounded-md text-sm transition-colors"
                        >
                            重試
                        </button>
                    )}
                </div>
            </div>
        </div>
    );
};

client/src/components/ai/
├── StreamingText.tsx      # 串流文字顯示
├── TypingIndicator.tsx    # 打字指示器
├── ChatBubble.tsx         # 對話氣泡
├── QuickReplies.tsx       # 快速回覆按鈕
├── AIResponseSkeleton.tsx # AI 回應骨架
└── ThemeToggle.tsx        # 主題切換