Hướng dẫn AI

Hướng dẫn Open Claude UI: Xây dựng giao diện hội thoại AI chân thực và hiệu ứng tương tác cấp production

Hướng dẫn này trình bày cách tích hợp open-claude-ui vào dự án React, TypeScript và Tailwind CSS, cấu hình design token cùng kiểu giao diện, kết hợp bộ chuyển đổi mô hình, vùng chứa cuộn mờ dần và ô nhập trò chuyện, đồng thời áp dụng guard cho bộ gõ, ghim cuộn, hiệu ứng lò xo và các mô-đun tương tác hỗ trợ khả năng truy cập.

15 tháng 10, 2026Thời gian đọc khoảng 28 phút

Hướng dẫn Open Claude UI: Xây dựng giao diện hội thoại AI chân thực

Giới thiệu dự án

open-claude-ui là thư viện component UI mã nguồn mở và công cụ tạo hiệu ứng dành cho các ứng dụng AI trên máy tính hiện đại. Dự án sử dụng framework REA để phân tích AST tĩnh, giải rối mã closure, theo dõi thời gian chạy và tái cấu trúc tài nguyên ASAR, sau đó hệ thống hóa kết quả nghiên cứu thành các component React, Hooks, kiểu giao diện và tài liệu kỹ thuật có thể tái sử dụng.

Dự án không chỉ tái tạo diện mạo giao diện mà còn tập trung khôi phục các cơ chế kỹ thuật ảnh hưởng đến cảm giác tương tác, chẳng hạn như tham số lò xo vật lý, bảo vệ bộ gõ CJK, hiệu ứng mờ dần ở mép vùng cuộn, điều khiển cuộn tin nhắn dạng streaming, thu phóng neo theo con trỏ, vùng chết khi kéo và âm báo tổng hợp bằng Web Audio.

Thông tin tuân thủ: Dự án không phân phối tài sản nhị phân độc quyền như phông chữ thương mại hoặc tệp ghi âm, mà sử dụng chuỗi fallback phông chữ hệ thống và hiệu ứng âm thanh thuần mã bằng Web Audio API. Dự án áp dụng MIT License; các kết quả liên quan chỉ phục vụ học tập, nghiên cứu và trao đổi kỹ thuật.

Phù hợp với những dự án nào

Nếu bạn đang phát triển ứng dụng trò chuyện AI, bảng điều khiển mô hình, giao diện phê duyệt gọi công cụ, trợ lý trên máy tính, trình xem media hoặc không gian cộng tác đa tác nhân, bạn có thể đưa các component cần thiết từ kho mã này vào dự án mà không phải tự điều chỉnh lại các token giao diện và tương tác phức tạp.

Ứng dụng AI trên web: Sử dụng bong bóng hội thoại, ô nhập văn bản phong phú, bộ chuyển đổi mô hình và bảng điều khiển Token.
Giao diện tạo nội dung dạng streaming: Sử dụng ghim cuộn, phần suy nghĩ có thể thu gọn và lớp phủ mờ dần.
Ứng dụng máy tính: Sử dụng factory cửa sổ Electron, thanh tiêu đề macOS và giải pháp vật liệu Vibrancy.
Ứng dụng Artifacts và đa phương tiện: Sử dụng kéo thả chia cột, lightbox media, chuyển cảnh phần tử dùng chung và cầu nối sandbox iframe.
Ứng dụng hỗ trợ khả năng tiếp cận: Sử dụng Hook di chuyển tiêu điểm Roving TabIndex theo định hướng WAI-ARIA.

Tính năng chính

Token thiết kế và hệ thống giao diện

Dự án cung cấp các cấp bề mặt tương phản thấp từ Surface 0 đến Surface 3, màu cam đất nung #d97757, cơ chế bù đường viền siêu mảnh cho màn hình độ phân giải cao, chuỗi fallback phông chữ hệ thống và ma trận bo góc dành cho nút, panel, bong bóng và ô nhập. Các biến giao diện toàn cục và keyframe được tập trung trong code-examples/cds-theme.css.

30 module mã độc lập

Kho mã gồm 11 control nguyên tử cơ bản và 19 module kiến trúc hoặc tương tác. Mã nguồn component nằm trong code-examples, còn entry point xuất TypeScript thống nhất nằm tại src/index.ts. Các module này bao phủ những trường hợp như nút, lựa chọn phân đoạn, ô nhập, bong bóng hội thoại, thẻ quyết định MCP, trình xem media, Diff streaming, cửa sổ desktop và canvas đa tác nhân.

Cơ chế tương tác cấp độ production

4 preset lò xo vật lý, gồm Bouncy, Snappy, Gentle và Heavy Snap.
Vùng cuộn sử dụng mặt nạ Alpha phi tuyến 7 cấp, tự động điều chỉnh tùy theo việc đã chạm đầu hay cuối vùng cuộn.
Ô nhập bảo vệ bộ gõ CJK bằng hai điều kiện isComposing và keyCode === 229.
Đầu ra streaming sử dụng dung sai đáy 40px và thời gian chờ cuộn thủ công 150ms, tránh việc tự động cuộn chiếm quyền điều khiển khung nhìn.
Dạng sóng microphone sử dụng ngưỡng cổng nhiễu 8% và nén Gamma với lũy thừa 0.7.
Tương tác kéo và gallery có vùng chết di chuyển con trỏ 4px để lọc rung nhẹ của tay.

Xem trước component ngoại tuyến

Kho mã đi kèm storybook tương tác một tệp docs/claude-components-storybook.html. Không cần khởi động máy chủ phát triển cục bộ, bạn vẫn có thể xem hệ màu đất nung, chế độ tối, phản hồi nút, capsule phân đoạn, hiệu ứng lò xo, ô đính kèm và hoạt ảnh trạng thái sao chép.

Cài đặt và chuẩn bị môi trường

Xác nhận stack kỹ thuật

Theo thông tin trong kho mã, dự án nên có môi trường sau:

React 18 hoặc cao hơn.
TypeScript 5.5 hoặc cao hơn.
Tailwind CSS 3.4 hoặc cao hơn.
Framer Motion 11 hoặc cao hơn.

README không cung cấp lệnh cài đặt cho một trình quản lý package cụ thể. Trước khi bắt đầu, hãy cấu hình workspace, dependency Git hoặc cách phát hành package để dự án có thể truy cập thông qua đường dẫn open-claude-ui, đồng thời bảo đảm các stack kỹ thuật peer nêu trên đã được thiết lập.

Xem storybook ngoại tuyến trước

Nếu đã lấy mã nguồn kho mã, bạn có thể mở trực tiếp tệp xem trước:

open docs/claude-components-storybook.html

Bước này giúp bạn xác nhận hiệu ứng giao diện, chủ đề tối và hiệu ứng tương tác của component có đáp ứng yêu cầu dự án hay không mà không cần chỉnh sửa dự án nghiệp vụ.

Cấu hình kiểu giao diện

Import CSS toàn cục

Import tệp chủ đề CDS trong entry point kiểu toàn cục của ứng dụng. Tệp này chứa các thuộc tính tùy chỉnh CSS và keyframe cần thiết cho component:

@import "open-claude-ui/code-examples/cds-theme.css";

Chủ đề cung cấp màu bề mặt, màu thương hiệu đất nung, đường viền, bóng đổ và nền tảng hiệu ứng. Để duy trì tính nhất quán giữa các component, nên ưu tiên sử dụng các biến CSS hiện có thay vì lặp lại màu hard-code trong từng component.

Mở rộng cấu hình Tailwind

Trong tailwind.config.js của dự án, hãy nạp phần mở rộng chủ đề do kho mã cung cấp:

const cdsTheme = require("open-claude-ui/code-examples/tailwind.config.js");

module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/open-claude-ui/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {
      ...cdsTheme.theme.extend
    }
  }
};

Mảng content cần bao phủ mã nguồn ứng dụng và các tệp chứa class Tailwind trong open-claude-ui. Nếu không, quá trình build production có thể không tạo ra các utility class mà component sử dụng.

Cách dùng cơ bản: Xây dựng khu vực điều khiển mô hình và nhập tin nhắn

Ví dụ dưới đây kết hợp ba module cốt lõi:

ScrollFadeContainer thêm hiệu ứng mờ dần ở mép trên và dưới cho vùng có thể cuộn.
ModelSwitcherWithTokenGauge hiển thị lựa chọn mô hình, trạng thái Extended Thinking và ngân sách Token.
ChatComposer cung cấp chức năng nhập tin nhắn chính và callback gửi.

import React, { useState } from 'react';
import {
  ChatComposer,
  ModelSwitcherWithTokenGauge,
  ScrollFadeContainer
} from 'open-claude-ui';

export function App() {
  const [model, setModel] = useState<
    'sonnet-3.5' | 'haiku-3.5' | 'opus-3'
  >('sonnet-3.5');
  const [thinking, setThinking] = useState(true);

  return (
    <div className="flex h-screen w-full bg-[var(--cds-surface-1)]">
      <ScrollFadeContainer
        axis="vertical"
        fadeSize={32}
        className="flex-1 p-6"
      >
        <div className="mx-auto max-w-3xl space-y-4">
          <ModelSwitcherWithTokenGauge
            currentModel={model}
            onModelChange={setModel}
            extendedThinking={thinking}
            onThinkingChange={setThinking}
            tokenBudget={{
              inputTokens: 12400,
              outputTokens: 3200,
              cacheReadTokens: 48000,
              cacheWriteTokens: 16000,
              maxContextWindow: 200000
            }}
          />

          <ChatComposer
            onSend={(text) => console.log('Send message:', text)}
          />
        </div>
      </ScrollFadeContainer>
    </div>
  );
}

Tìm hiểu về quản lý trạng thái

currentModel và extendedThinking đều do tầng ứng dụng quản lý, vì vậy bộ chuyển đổi mô hình có thể đồng bộ với cấu hình yêu cầu mô hình thực tế. tokenBudget trong ví dụ truyền riêng số Token đầu vào, đầu ra, đọc cache, ghi cache và cửa sổ ngữ cảnh tối đa vào bảng điều khiển.

Trong ví dụ, onSend của ChatComposer chỉ ghi log. Khi tích hợp vào dự án thực tế, bạn có thể gọi dịch vụ hội thoại, cập nhật danh sách tin nhắn và kích hoạt trạng thái phản hồi streaming trong callback này.

Hướng dẫn chọn component thường dùng

Control cơ bản

CdsButton: Cung cấp bốn kích thước XS, SM, MD, LG và năm biến thể Primary, Secondary, Ghost, Outline, Danger.
SegmentedControl: Dùng để chuyển đổi chế độ, hỗ trợ định vị hình học thuần túy và giải pháp hoạt ảnh layoutId của Framer Motion.
StatusIndicators: Bao gồm đèn thở đất nung, xung hoạt động thời gian thực, hoạt ảnh ba chấm suy nghĩ và hiệu ứng quét sáng skeleton.
ConfirmationDialog: Dùng để xác nhận thao tác mặc định hoặc nguy hiểm, bao gồm lớp phủ mờ và ràng buộc tiêu điểm bàn phím.
AttachmentCard: Hỗ trợ hai cách hiển thị tệp đính kèm: ô dạng tile trên desktop và capsule nội dòng trong ô nhập.

Hội thoại và gọi công cụ

ChatMessageBubbles: Phân biệt bong bóng người dùng và kiểu trình bày trong suốt của trợ lý.
ThinkingAccordion: Hiển thị quá trình suy nghĩ có thể thu gọn, đồng thời có thể giữ trạng thái mở bắt buộc trong khi tạo nội dung.
RichComposerWithMentions: Phù hợp với terminal nhập liệu cần lệnh /, ngữ cảnh @ và dự đoán Token.
McpToolDecisionCard: Dùng cho quy trình cấp quyền công cụ, bao phủ các trạng thái pending_approval, running, success và error.

Media, mã và Artifacts

MediaLightboxViewer: Cung cấp vùng gallery rộng 75vw, Pan/Zoom neo theo con trỏ, vùng chết khi kéo và thu phóng bằng con lăn Ctrl.
ArtifactsSplitPaneResizer: Xử lý thay đổi kích thước hai cột, thu gọn ở mép, hấp thụ về tỷ lệ 50/50 khi nhấp đúp và nhiễu sự kiện con trỏ iframe.
EpitaxyIframeBridge: Kết nối sandbox xem trước thông qua kiểm tra Origin và giao thức RPC postMessage được cô lập.
StreamingDiffViewer: Hỗ trợ nối thêm streaming gia tăng cùng hai chế độ Diff thống nhất và chia đôi.
CodeBlock: Cung cấp vùng chứa mã và trạng thái sao chép tự suy giảm sau 2.5 giây.

Thực hành nâng cao

Bảo vệ bộ gõ tiếng Trung, tiếng Nhật và tiếng Hàn

Nếu ô nhập chat cần tự mở rộng sự kiện bàn phím, phải giữ nguyên cơ chế bảo vệ quá trình ghép chữ của bộ gõ. Khi người dùng nhấn Enter trong cửa sổ gợi ý chữ Hán hoặc kana, tin nhắn không được gửi. Dự án sử dụng hai điều kiện kiểm tra:

const composing =
  event.nativeEvent.isComposing || event.keyCode === 229;

if (event.key === 'Enter' && !composing) {
  // Gửi tin nhắn
}

Với phím Escape, cũng cần tránh để sự kiện tiếp tục nổi bọt khi đóng lớp gợi ý của bộ gõ, nếu không cửa sổ hội thoại có thể bị đóng ngoài ý muốn.

Tránh để đầu ra dạng luồng chiếm quyền vị trí cuộn

Có thể dùng useClaudeScrollPinning để quản lý Token được nối thêm liên tục. Chiến lược cốt lõi gồm dung sai đáy 40px, thời gian hạ nhiệt 150ms sau khi cuộn thủ công và vùng đệm đàn hồi 35vh. Khi người dùng ở gần cuối, giao diện có thể theo sát đầu ra; ngay khi người dùng chủ động cuộn lên xem tin nhắn cũ, tính năng tự động cuộn không nên lập tức kéo khung nhìn trở lại cuối.

Thống nhất sử dụng các preset chuyển động

Dự án cung cấp bốn cấu hình lò xo đã được tinh chỉnh trong ClaudeMotionPresets.ts. Khi phát triển component mới, hãy ưu tiên tái sử dụng Bouncy, Snappy, Gentle hoặc Heavy Snap thay vì tùy ý thiết lập độ cứng và lực cản cho từng animation. Nhờ đó, nút, panel, thao tác kéo thả, hiệu ứng hút và chuyển cảnh phần tử dùng chung có thể duy trì cùng một ngôn ngữ vật lý.

Xử lý đúng thao tác kéo chia cột iframe

Khi thanh chia cột đi qua iframe, iframe có thể bắt sự kiện con trỏ và làm gián đoạn thao tác kéo. ArtifactsSplitPaneResizer sẽ bật cơ chế ngăn nuốt sự kiện khi thao tác kéo được kích hoạt, đồng thời kết hợp vùng chết di chuyển 4px, giới hạn biên và cơ chế hút về giữa khi nhấp đúp. Nếu ứng dụng có phần xem trước Artifacts, hãy ưu tiên tái sử dụng module này thay vì chỉ lắng nghe sự kiện chuột trên chính thanh chia cột.

Duy trì đầy đủ điều hướng cho người dùng bàn phím

useClaudeRovingFocus hỗ trợ điều hướng bằng phím mũi tên một chiều hoặc hai chiều, chuyển đến biên bằng Home và End, cũng như lật đối xứng theo RTL. Khi xây dựng lưới mô hình, danh sách tệp đính kèm hoặc dãy thẻ công cụ, đồng thời cần duy trì ngữ nghĩa ARIA chính xác và trạng thái tiêu điểm hiển thị.

Xử lý giới hạn tốc độ và lỗi dịch vụ của mô hình

useRateLimitBackoff dành cho phản hồi 429 và 503, cung cấp cơ chế lùi theo cấp số nhân có giới hạn, thêm jitter và phục hồi tự động sau ba lần ngắt mạch. Nó phù hợp với lớp yêu cầu mô hình, nhưng nghiệp vụ vẫn cần dựa trên cấu trúc phản hồi API của mình để quyết định khi nào thử lại, khi nào hiển thị lỗi và khi nào cho phép người dùng khôi phục thủ công.

Học chuyên sâu qua sổ tay kỹ thuật

Ngoài mã nguồn component, kho lưu trữ còn cung cấp sổ tay kỹ thuật hệ thống thiết kế dài hơn 3.000 dòng. Khuyến nghị đọc theo thứ tự sau:

Trước tiên đọc triết lý thiết kế, thang màu Surface, ma trận bo góc và quy tắc đường viền mảnh.
Tiếp theo tìm hiểu nút, điều khiển phân đoạn, chỉ báo trạng thái và hộp thoại xác nhận.
Sau đó nghiên cứu tính năng nhập hội thoại, lớp bảo vệ CJK, chuyển đổi mô hình và máy trạng thái MCP.
Khi cần hiệu ứng chuyển động phức tạp, hãy xem các tham số lò xo, ánh sáng môi trường và mặt nạ cuộn.
Khi phát triển ứng dụng desktop, công cụ đa phương tiện hoặc không gian cộng tác, hãy đọc chương kiến trúc hệ thống tương ứng.

Sổ tay đầy đủ nằm tại docs/Claude Design System (CDS).md. Công việc phân tích ngược của dự án được thực hiện với sự hỗ trợ của REA.

Phối hợp với AI Coding Agent

Kho lưu trữ cung cấp AGENTS.md, CLAUDE.md, .cursorrules và các tệp chỉ dẫn Copilot. Khi dùng Cursor, Claude Code, GitHub Copilot hoặc các công cụ tương tự để tạo giao diện mới, có thể yêu cầu Agent tuân thủ token hiện có, preset lò xo, nguyên tắc đường viền và quy tắc bảo vệ bộ gõ của kho lưu trữ.

Ví dụ lời nhắc: Vui lòng tuân thủ nghiêm ngặt các quy định trong AGENTS.md của kho lưu trữ này, sử dụng token thiết kế đất nung CDS và preset lò xo ClaudeMotionPresets để xây dựng component hiện tại.

Tổng kết

open-claude-ui tổ chức token trực quan, điều khiển hội thoại, vật lý chuyển động, tương tác đa phương tiện và kiến trúc desktop của ứng dụng AI thành các module có thể tái sử dụng. Cách tích hợp ổn định nhất là trước tiên xác nhận hiệu ứng qua Storybook ngoại tuyến, sau đó đưa vào CSS chủ đề và phần mở rộng Tailwind, cuối cùng bắt đầu kết hợp từ các component cốt lõi như ô nhập chat, bộ chuyển đổi mô hình và vùng cuộn. Với các tình huống phức tạp như đầu ra dạng luồng, nhập CJK, kéo iframe và điều hướng bằng bàn phím, nên tận dụng các Hook và máy trạng thái có sẵn trong kho lưu trữ thay vì chỉ sao chép kiểu hiển thị bề mặt.