Hướng dẫn đóng góp nội dung

proto.lib là thư viện các animation HTML tự chứa về giao thức mạng, đặc tả kỹ thuật và case study. Mỗi animation là một thư mục độc lập — thêm nội dung mới không cần đụng vào mã nguồn ứng dụng. Trang này mô tả đầy đủ cách thêm animation, thêm danh mục và triển khai.

Mô hình nội dung

Toàn bộ nội dung nằm trong content/animations/. Mỗi animation là một thư mục theo slug:

content/animations/<slug>/
├── index.html   # animation HTML tự chứa (CSS/JS/SVG inline)
└── meta.json    # metadata mô tả animation

Khi build, site quét thư mục này, đọc meta.json và tự sinh trang xem, mục thư viện, tìm kiếm và bộ lọc. Không có bước đăng ký thủ công nào khác.

Thêm một animation mới

Bước 1 — Tạo thư mục và index.html

Tạo content/animations/<slug>/index.html. File này phải tự chứa hoàn toàn: mọi CSS, JavaScript, SVG, font đều inline; không gọi tài nguyên mạng ngoài (CDN, ảnh từ xa, fetch…). Đây là điều kiện để animation chạy ổn định trong iframe sandbox và không phụ thuộc mạng.

Mẹo (không bắt buộc): nếu animation tự báo chiều cao qua postMessage({ type: "protolib:height", height }), khung xem trên trang chi tiết sẽ tự giãn theo nội dung, tránh việc người dùng phải cuộn hai lớp.

Nên tôn trọng prefers-reduced-motion để tắt/giảm hiệu ứng cho người dùng nhạy cảm với chuyển động.

Bước 2 — Khai báo meta.json

{
  "title": "TCP: Bắt tay 3 bước",
  "description": "Mô tả ngắn hiển thị ở thẻ và trang chi tiết.",
  "category": "transport",
  "tags": ["tcp", "handshake", "rfc-9293"],
  "difficulty": "basic",
  "references": [
    { "label": "RFC 9293 — TCP", "url": "https://www.rfc-editor.org/rfc/rfc9293" }
  ],
  "date": "2026-07-02",
  "featured": false
}

Build sẽ thất bại có chủ đích nếu meta.json sai (thiếu trường bắt buộc, category hoặc difficulty không hợp lệ) — để không bao giờ deploy dữ liệu hỏng.

Bước 3 — Triển khai

• Có Git integration: commit & push lên origin → Vercel tự build và phát hành. Animation xuất hiện ngay trong thư viện, tìm kiếm và trang danh mục.
• Thủ công: vercel deploy --prod.

Hai cách tạo index.html

Cách 1 — Dùng script sequence-diagram (khuyến nghị cho giao thức)

Các animation dạng sơ đồ tuần tự (actor + message theo bước) dùng chung một engine. Chỉ cần khai báo cấu hình trong scripts/generate-animations.mjs rồi chạy:

node scripts/generate-animations.mjs

Mỗi entry gồm slug, meta, subtitle và config với:

• actors: danh sách nhân vật (id, label, sub, color, state).
• steps: từng bước gồm desc (giải thích) và msgs (các message: from/to/label/color, hoặc { type: "note", at, label }). Đặt parallel: true để các message trong bước chạy đồng thời; states để cập nhật badge trạng thái của actor.

Engine lo sẵn play/pause, tua từng bước, phím tắt, tôn trọng reduced-motion và tự báo chiều cao — nên đây là cách nhanh và nhất quán nhất.

Cách 2 — HTML tự viết tay

Với nội dung không phải sơ đồ tuần tự (đồ thị, mô phỏng tùy biến…), cứ đặt một index.html tự chứa bất kỳ vào thư mục animation. Miễn là tự chứa, nó sẽ được nhúng và hiển thị bình thường.

Thêm một danh mục mới

Danh mục khai báo tập trung trong lib/categories.ts. Thêm một phần tử vào mảng CATEGORIES:

{
  slug: "concurrency",
  name: "Concurrency",
  nameVi: "Đồng thời & Song song",
  description: "Mô tả ngắn hiển thị ở thẻ danh mục.",
  accent: "#A3E635",
}

Sau đó chỉ cần dùng slug này trong meta.json của animation. Trang chủ, bộ lọc và trang danh mục tự cập nhật.

Nguyên tắc chất lượng

• Tự chứa tuyệt đối — không tài nguyên mạng ngoài.
• Chính xác kỹ thuật — bám sát RFC/spec và ghi references tới nguồn gốc.
• Dễ đọc — mỗi bước một ý; nhãn ngắn gọn; thuật ngữ giữ nguyên tiếng Anh, giải thích bằng tiếng Việt.
• Truy cập được — tôn trọng prefers-reduced-motion, tương phản màu đủ ở cả giao diện sáng/tối.