Oil UI
Hướng dẫn Agent · Cursor / Windsurf / IDE

Sử dụng Oil UI trong Cursor, Windsurf & các Coding Agent trên IDE

Nhiều lập trình viên thiết kế và tinh chỉnh giao diện trực tiếp ngay trong Cursor, Windsurf, Antigravity hoặc Gemini CLI song song với mã ứng dụng. Vì Oil UI dùng định dạng skill mở, chỉ một lệnh npx skills add oil-oil/oil-ui là đủ trang bị cho các agent trên IDE cùng một quy trình ưu tiên tác vụ: khám phá hướng thiết kế, triển khai đủ trạng thái trong stack của bạn và kiểm tra ảnh chụp thực tế.

Điểm chính

Một trình cài đặt dùng chung cho các coding agent phổ biến

chạy npx skills add oil-oil/oil-ui rồi chọn Cursor, Windsurf, Claude Code hoặc Codex.

Điểm chính 2

Khi làm mới màn hình trong codebase sẵn có, hãy giới hạn mỗi prompt vào một trang hoặc một luồng người dùng và liệt kê rõ props, hook, route nào không được đụng tới.

Điểm chính 3

Với các module UI độc lập (trình tải tệp, thanh toán, bộ cấu hình), hãy yêu cầu agent triển khai đủ trạng thái chờ, đang thao tác, hoàn tất và lỗi ngay từ đầu.

Điểm chính 4

Để IDE agent mở dev server cục bộ và xem ảnh chụp trình duyệt thật ở 1440px và 390px thay vì chỉ đọc code diff.

Cài đặt Oil UI Skill mã nguồn mở miễn phí cho Cursor, Windsurf & IDE agent
npx skills add oil-oil/oil-ui

Hỗ trợ cả cài đặt theo phạm vi dự án (chia sẻ cùng nhóm) và cài đặt ở mức người dùng.

Cài đặt Oil UI trên các IDE và CLI Agent

Dù bạn làm việc trong thanh agent của Cursor, Windsurf Cascade, Antigravity hay agent dòng lệnh, Oil UI đều cung cấp cùng một quy trình thiết kế và danh sách kiểm tra trực quan.

  1. Chạy trình cài đặt skill tương tác

    Chạy lệnh ở thư mục gốc dự án hoặc terminal rồi chọn các coding agent bạn dùng hằng ngày.

    npx skills add oil-oil/oil-ui
  2. Dùng cài đặt phạm vi dự án để đồng bộ cả nhóm

    Chọn phạm vi dự án sẽ đặt skill ngay trong repository, giúp IDE agent của mọi thành viên tuân theo cùng tiêu chuẩn bố cục và review.

  3. Gọi tên Oil UI tường minh trong prompt

    Mở đầu prompt giao diện bằng "Use Oil UI to design..." hoặc "Use Oil UI to refresh this screen..." để agent chạy đúng quy trình thiết kế thay vì vá CSS tùy tiện.

Bốn thói quen khi thiết kế ngay trong codebase sẵn có

Lỗi phổ biến nhất khi dùng IDE agent là trộn lẫn hạ tầng backend với thiết kế lại toàn bộ giao diện trong một prompt dài lê thê. Tách bạch phạm vi giúp cả mã nguồn lẫn bố cục gọn gàng:

Giới hạn mỗi lần vào một module độc lập hoặc một luồng tác vụ
Hoàn thiện trọn vẹn một module — như module tải tệp Chute hay bộ cấu hình bàn phím cơ KEEB trong thư viện — trước khi chuyển sang các màn hình lân cận.
Nêu rõ data hook và handler nào bị cấm sửa
Khi cập nhật một view React hoặc Vue đang chạy, hãy dặn agent: "Giữ nguyên state biểu mẫu, API mutation và route params hiện tại; chỉ làm lại bố cục, phân cấp và phản hồi trạng thái."
So sánh hướng mới trên một route nháp trước khi gộp
Nếu một trang cần hướng thị giác mới, hãy để agent render 3 phương án khác biệt cạnh nhau trước, rồi chuyển phương án đã chọn vào các component chính.
Luôn kiểm chứng trên localhost ở kích thước desktop và di động
Trước khi chấp nhận diff, hãy bảo agent mở dev server đang chạy và chụp ảnh 1440px và 390px để bắt lỗi tràn khung, giãn cách chật hoặc độ tương phản hỏng.

Prompt tái sử dụng để tinh chỉnh module trong Cursor & Windsurf

Gắn thẻ tệp component mục tiêu trong khung chat IDE và dùng cấu trúc này để nhận về phần triển khai đủ mọi trạng thái:

Prompt cho IDE agent khi làm module UI tương tác
Dùng Oil UI để thiết kế và triển khai [tên module, ví dụ: module tải tệp chia sẻ / bộ cấu hình sản phẩm] trong repository này.
- Ràng buộc codebase: Giữ nguyên không đổi các [hooks, props và API types] hiện có.
- Các trạng thái bắt buộc: Triển khai 1) trạng thái chờ mặc định, 2) phản hồi khi kéo/nhập đang diễn ra, 3) trạng thái tiến trình và hoàn tất (kèm xác nhận sao chép/chia sẻ), và 4) trạng thái lỗi kiểm tra hợp lệ hoặc vượt giới hạn.
- Kỷ luật thị giác: Tránh bọc thẻ lồng trong thẻ và tránh các nhãn pill tiêu đề trang trí. Thiết lập phân cấp bằng tỷ lệ typography, khoảng cách và trạng thái focus rõ ràng, rồi kiểm chứng trên trình duyệt cục bộ.

Rất hiệu quả khi gắn kèm tệp component đang có trong Cursor hoặc Windsurf.

Ví dụ thực tế & prompt trong thư viện

Xem bộ sưu tập →
Oil UI Pro

Mở khóa quy trình cải tạo dự án sẵn có & tinh chỉnh component với Oil UI Pro

Oil UI Pro bổ sung các quy trình riêng cho codebase sẵn có — gồm chẩn đoán có chú thích trên một trang, hệ thống cải tạo 3 bước (dọn gọn / nâng cấp / làm lại luồng + DESIGN.md) và tinh chỉnh chuyên sâu từng component.

Khám phá Oil UI Pro →
Sao chép prompt cài đặt Pro
npx github:oil-oil/oil-cli install oil-ui-pro

Câu hỏi thường gặp

Nên chọn model nào trong Cursor hoặc Windsurf khi dùng Oil UI?

Hãy dùng Claude Opus hoặc các model GPT/Codex đầu bảng khi khám phá hướng thị giác mới hoặc tái cấu trúc trang phức tạp. Khi đã chốt hướng thiết kế hoặc DESIGN.md, Claude Sonnet và các model nhanh hơn làm rất tốt việc triển khai các trạng thái sang những màn hình tương tự.

Oil UI có dùng chung được với shadcn/ui, Radix hoặc Tailwind không?

Có. Các thư viện primitive lo phần điều khiển và khả năng truy cập (accessibility), còn Oil UI lo bố cục trang, phân cấp thị giác, khám phá hướng thiết kế và loại bỏ chi tiết rập khuôn. Chúng bổ trợ cho nhau rất gọn.

Làm sao bảo đảm agent không làm hỏng click handler hay kiểm tra biểu mẫu hiện có?

Hãy liệt kê các handler cần giữ nguyên trong prompt và làm theo bước kiểm thử luồng của Oil UI: bấm đi hết luồng chính và cố ý gửi biểu mẫu lỗi ngay trên trình duyệt trước khi kết thúc.

Nhóm tôi có thể dùng cả Cursor lẫn Claude Code / Codex trên cùng một repository không?

Có. Hãy chọn tất cả agent liên quan khi chạy npx skills add oil-oil/oil-ui hoặc commit một tệp DESIGN.md dùng chung để mọi công cụ đọc cùng một bộ quy tắc thiết kế.

Hướng dẫn liên quan

Hướng dẫn thiết kế UI trên Claude Code ↗Cải tạo UI dự án sẵn có ↗Khắc phục UI AI rập khuôn ↗