VINASIGagent

Điểm bắt đầu cho agent

Dành cho SI agents

Lộ trình rõ ràng để tìm ngữ cảnh dự án, quy tắc giao diện liên quan và nguồn triển khai đúng.

Hệ thống thiết kế đang dự thảo

Không coi hướng dẫn là chính sách VINASIG đã duyệt hay áp dụng cho dự án khác trước khi kiểm tra hướng dẫn của dự án đó.

Định hướng giao diện mặc định

Tối giản sáng và vui

Theo định hướng dự thảo của hệ thống trừ khi yêu cầu hoặc quyết định sản phẩm đã duyệt cụ thể hơn.

  • Dùng bố cục phẳng, tối giản, ưu tiên nội dung với bề mặt trung tính sáng.
  • Dùng màu nhận diện chọn lọc, tiết chế chi tiết pixel hoặc vuông bo góc.
  • Chỉ thêm hình minh họa khi giúp giải thích nội dung hoặc hành động của người dùng.
  • Không thêm màu chuyển, tiêu đề quá lớn, thẻ lặp không có nội dung riêng, hình viên thuốc, nhãn hay chữ thừa theo thói quen. Dùng thẻ khi làm rõ nhóm nội dung thực.
  • Chỉ học một đặc điểm từ Apple, GitHub hoặc Duolingo khi được yêu cầu. Không sao chép hay trộn toàn bộ phong cách của họ.
Đọc định hướng giao diện đầy đủ

Kiểm tra hoàn tất web bắt buộc

Đừng quên biểu tượng thẻ trình duyệt

Logo ở đầu trang không thiết lập biểu tượng trên thẻ trình duyệt, dấu trang và các vùng khác của trình duyệt.

Trước khi hoàn tất việc web

  • Kiểm tra phần head hoặc bố cục chung và xác nhận có tham chiếu biểu tượng thẻ.
  • Dùng bản xuất chính thức 16 x 16, 32 x 32 và 48 x 48 px khi có.
  • Kiểm tra đường dẫn biểu tượng có tính đường dẫn gốc khi triển khai và mọi tệp đều có trong bản build.
  • Báo biểu tượng nguồn bị thiếu thay vì bỏ qua hoặc tự vẽ bản thay.

Tham chiếu biểu tượng thẻ VINASIG

<link rel="icon" type="image/png" sizes="16x16" href="/brand/favicons/favicon-16.png" />
<link rel="icon" type="image/png" sizes="32x32" href="/brand/favicons/favicon-32.png" />
<link rel="icon" type="image/png" sizes="48x48" href="/brand/favicons/favicon-48.png" />
Xem hướng dẫn logo và tệp biểu tượng thẻ được cung cấp

Kiểm tra hoàn tất giao diện bắt buộc

Tùy chỉnh điều khiển khi đóng chỉ là một nửa công việc. Bảng lựa chọn khi mở vẫn có thể dùng giao diện mặc định của trình duyệt hoặc hệ điều hành.

Trước khi hoàn tất việc giao diện

  • Mở mọi điều khiển chọn và danh sách thả xuống liên quan đến việc sửa. Kiểm tra bảng lựa chọn thật.
  • Khi thiết kế cần giao diện tùy chỉnh, tạo kiểu cả nút mở và bảng mở.
  • Giữ tiêu điểm nhìn thấy, chọn bằng bàn phím, Escape để đóng và thông báo trạng thái chọn hỗ trợ tiếp cận.
  • Kiểm tra bảng lựa chọn luôn gắn với điều khiển và nằm gọn trên màn hình hẹp.

Quy trình đề xuất

Nạp ngữ cảnh qua vài bước có chủ đích

Dùng nguồn hẹp nhất trả lời công việc, rồi kiểm tra thẩm quyền và trạng thái.

Bước 01

Đọc hướng dẫn dự án

Bắt đầu từ AGENTS.md của web đang dùng, rồi AGENTS.md gốc của kho này nếu công việc cần hệ thống.

Bước 02

Tìm quy tắc phù hợp

Dùng mục nền tảng, thành phần, mẫu hoặc phần tử phù hợp. Xem ví dụ đã hiển thị và nhãn nền tảng trước khi áp dụng.

Bước 03

Kiểm tra trạng thái và nguồn

Theo quy tắc đã duyệt khi có. Đánh dấu quy tắc bản mẫu là dự thảo và giữ thay đổi biến thiết kế trong tệp nguồn.

Rà soát giao diện bắt buộc

Build thành công vẫn cần kiểm tra trên trình duyệt

Người dùng Reddit gần đây phản ánh bố cục quá nhiều thẻ giống nhau, chữ tràn trên màn hình nhỏ, sai khác với tham chiếu hình ảnh, đổi loại điều khiển và bản sửa gây lỗi mới. Người khác đạt kết quả tốt hơn với quy tắc thiết kế rõ và ảnh chụp. Đây là trải nghiệm riêng, không phải tỷ lệ lỗi.

Trước khi viết mã

  • Đọc tóm tắt dự án, hướng dẫn giao diện liên quan, biến thiết kế, tài sản và thành phần hiện có.
  • Ghi trang đã sửa, hành động, trường hợp nội dung biên, kích thước màn hình và chuyển trạng thái quan trọng.
  • Ghi định hướng bằng lựa chọn bố cục, màu, chữ và hình dạng cụ thể. Giữ nhận diện dự án và không lấp chỗ trống bằng phong cách sinh tự động chung chung.
  • Không thêm nhãn phiên bản, nhãn dự thảo, chân trang bản mẫu, điều hướng lặp hoặc liên kết mục lục cho máy trừ khi được yêu cầu, bắt buộc hoặc đáp ứng nhu cầu rõ ràng. Giữ ghi công và thông báo pháp lý bắt buộc.
  • Khi có ảnh hoặc đường dẫn tham chiếu, ghi phần cần khớp và giữ loại điều khiển cùng cách hoạt động dự định.

Trước khi hoàn tất công việc

  • Kiểm tra trang thật ở khoảng 1440, 1024, 768, 390 và 320 CSS px khi thực tế cho phép.
  • So sánh bản hiển thị với tài liệu tham chiếu ở cùng màn hình. Kiểm tra chữ trên màn hình nhỏ, tràn, vị trí và cách hoạt động.
  • Kiểm tra nội dung dài, phóng to, danh sách đang mở, tiêu điểm, bàn phím và tràn trang.
  • Kiểm tra điều khiển đã sửa trong cây hỗ trợ tiếp cận của trình duyệt. Mỗi điều khiển cần đúng vai trò, tên và trạng thái chọn hoặc mở.
  • Kiểm tra độ tương phản của chữ và biểu tượng trên nền thực tế, cùng chế độ giảm chuyển động khi liên quan.
  • Sửa việc cắt nội dung từ nguyên nhân. Không che lỗi bố cục bằng quy tắc tràn cho toàn trang.
  • Nếu cùng lỗi hình ảnh vẫn còn sau hai lần sửa đúng phạm vi, dừng và tìm nguyên nhân bố cục hoặc xung đột kiểu trước khi thêm quy tắc ghi đè.
  • Kiểm tra lại trang bị ảnh hưởng sau thay đổi cuối và báo phần chưa xác minh được.

Nghiên cứu và quy tắc

Đo lường gần đây thấy điều khiển không có tên trong một số web mẫu và lỗi cấu trúc hỗ trợ tiếp cận trong một đợt kiểm tra giao diện khác. Một đánh giá cũng thấy lỗi hỗ trợ tiếp cận tự động trong trang do GPT-5.6 Luna tạo. Phương pháp các nghiên cứu này có phạm vi hẹp, không dự đoán mọi dự án. Chúng củng cố việc kiểm tra ngữ nghĩa và bản hiển thị trên trình duyệt.

Đọc WCAG 2.2Đọc đánh giá khả năng tiếp cậnĐọc đánh giá mô hình gần đâyĐọc đo lường cây hỗ trợ tiếp cậnĐọc báo cáo kiểm tra giao diện được tạoĐọc nghiên cứu đồng nhất hóa thiết kế

Danh sách kiểm tra đầy đủ và ghi chú nguồn

Đọc docs/agents/ui-quality.md để xem quy trình đầy đủ, giới hạn bằng chứng, kết quả riêng dự án, phản ánh Reddit gần đây và nguồn chú giải.

Thêm vào kho mã của web

Giữ ngữ cảnh gần mã

Nhập quy tắc làm việc chung rồi ghi commit nguồn thiết kế cùng ngoại lệ đã được dự án duyệt.

# AGENTS.md in a consuming website repository

## VINASIG working and interface guidance
- Import a reviewed VINASIG/agent-standards snapshot with its approved digest.
- Keep the generated AGENTS.md block, local manifest and .agents/skills files.
- Start a fresh agent session to check discovery of the installed skills.
- Record the VINASIG/web-design-system source commit used by this project.
- Read the matching foundation, component specification and rendered example.
- Review source tokens and components against the project's approved design.
- Current design guidance is draft and requires owner approval.

Chỉ đặt đường dẫn hoặc liên kết Markdown không nhập được hướng dẫn hay cài đặt thành phần. Kho này chưa có gói npm của hệ thống thiết kế được phát hành.

Đọc quy trình tích hợp quy tắc chung

Viết quy tắc agent đọc được

Mỗi hướng dẫn cần trực tiếp và truy được nguồn

  • Bắt buộcQuy tắc áp dụng khi phạm vi đã nêu được đáp ứng.
  • Ưu tiênLựa chọn được đề xuất. Ghi lý do khi dự án cần ngoại lệ.
  • Tùy chọnLựa chọn được phép, có thể dùng khi phù hợp.

Mỗi quy tắc cần phạm vi, tệp nguồn và trạng thái phê duyệt. Thêm ví dụ nhỏ hoạt động được khi quy tắc ảnh hưởng mã hoặc tương tác.

Bản đồ nguồn

Nơi tìm thông tin chuẩn

Ngữ cảnh dự án và agent

AGENTS.md dẫn tới quy tắc làm việc chung và ngữ cảnh dự án bắt buộc. docs/agents/project-guide.md giữ hướng dẫn thiết kế đầy đủ.

Rà soát giao diện cho SI agent

docs/agents/ui-quality.md định nghĩa quy trình chất lượng có nghiên cứu và điều kiện hoàn tất cho việc giao diện.

Nhận diện thương hiệu

docs/brand/README.md ghi thông tin phiên bản logo, đường dẫn xuất và hướng dẫn sử dụng dự thảo.

Hướng dẫn thiết kế

docs/ chứa đặc tả nguồn cho nền tảng, thành phần và mẫu giao diện.

Thư viện phần tử giao diện

docs/elements/catalog.json định nghĩa cả 81 mục. Mở ví dụ hiển thị phù hợp và kiểm tra nhãn nền tảng trước khi dùng.

Biến thiết kế triển khai

src/styles/tokens.css định nghĩa màu nhận diện, vai trò theo ý nghĩa, bảng mở rộng tùy chọn, biến giao diện chung và phông chữ lưu tại chỗ.

Mục lục đã công bố

/llms.txt cung cấp bản đồ điều hướng gọn cho công cụ có thể đọc web tài liệu.