scroll-craft: Agent Skill Biến Claude Code & Codex Thành Nghệ Nhân Thiết Kế Website Scrollytelling Đỉnh Cao

Trong làn sóng bùng nổ của AI sinh mã (Generative UI & Coding Agents), hầu hết các trang web do AI tạo ra thường rơi vào một trong hai thái cực đáng thất vọng: Hoặc là cực kỳ khuôn mẫu, buồn tẻ với cùng 6 khối layout quen thuộc (Hero -> Logos -> 3 Cột tính năng -> Bảng giá -> FAQ -> Footer); hoặc là lạm dụng hoạt họa lòe loẹt, chữ mảnh tương phản kém 2.1:1, tiêu đề bị ngắt thành 6 dòng trên điện thoại và làm đơ trình duyệt của người dùng.

Hầu hết các trang web do AI tạo ra đều thất bại vì tách rời tương tác khỏi tay nghề thiết kế. scroll-craft được tạo ra để coi Tương Tác (Interaction) và Tay Nghề (Craft) là một thể thống nhất, mang lại tiêu chuẩn nghệ thuật thực thụ cho các Coding Agents.

Định nghĩa scroll-craft **scroll-craft** là một Agent Skill và Plugin dành cho **Claude Code**, **Codex** hoặc bất kỳ trợ lý AI nào có khả năng đọc chỉ thị, sửa tệp và tương tác với trình duyệt. Nó nạp toàn bộ tri thức thiết kế tương tác cao cấp, công cụ kiểm định và bộ khung quy chuẩn để AI tạo ra các website chuẩn Scrollytelling như Apple hay Awwwards.

Khác với các website truyền thống nơi thanh cuộn chỉ đơn thuần là công cụ di chuyển màn hình lên xuống, scroll-craft biến **con lăn chuột thành một bộ điều khiển thời gian (scrubber)** tương tự như thanh trượt trong phần mềm biên tập phim chuyên nghiệp:

• **Video chà khung hình (Video Scrubbing):** Video không tự động phát video clip ngẫu nhiên, mà từng khung hình tiến lùi chính xác theo từng milimet ngón tay người dùng cuộn chuột.
• **Ghim phân đoạn (Section Pinning):** Phân đoạn quan trọng được ghim chặt cố định giữa màn hình trong khi các lập luận, dữ liệu và hình khối biến đổi liên tục xung quanh nó.
• **Đường ray chuyển động ngang (Horizontal Rails):** Tự động chuyển đổi chuyển động cuộn dọc thành chuyển động trượt ngang êm ái khi đi qua các bộ sưu tập hoặc dòng thời gian.
• **Phản hồi con trỏ độc lập (Pointer Response):** Con trỏ chuột điều khiển các góc nghiêng 3D, hiệu ứng ánh sáng cạnh (edge light) độc lập hoàn toàn với việc trang có đang cuộn hay không.

Nguyên tắc vàng của Engine File `scrollcraft.js` và `scrollcraft.css` là cơ chế cốt lõi và **tuyệt đối không bao giờ bị sửa đổi theo từng dự án**. Mọi hiệu ứng tùy biến đều được thúc đẩy thông qua biến CSS tùy biến `--sc-p` (phần trăm tiến độ cuộn) mà engine phát ra.

Để ngăn chặn tình trạng "mọi website AI trông đều giông giống nhau", scroll-craft đưa ra 8 hệ ngữ pháp trang hoàn toàn loại trừ lẫn nhau. Nếu một trang chọn ngữ pháp này, nó **bị cấm tuyệt đối** sử dụng các thành phần bắt buộc của ngữ pháp khác:

Điểm độc đáo chưa từng thấy ở bất kỳ thư viện nào khác chính là cơ chế **Fingerprint Gate (Cổng đối soát vân tay)**. Trong thư mục làm việc luôn tồn tại tệp `FINGERPRINTS.md` ghi nhận lịch sử các trang bạn đã làm.

• **Quy tắc khác biệt 4/6:** Một trang web mới muốn được phê duyệt bắt buộc phải khác biệt với mọi trang bạn từng xây dựng trên ít nhất 4 trong 6 chiều: Ngữ pháp trang, Cấu trúc thanh điều hướng, Kiểu màn hình Hero, Hình thái các hồi (Acts), Cách kết thúc trang, và Tuyệt kỹ độc bản.
• **Tuyệt kỹ độc bản (Required Signature Move):** Mỗi website được tạo ra bắt buộc phải phát minh ra một tương tác độc nhất vô nhị chỉ xuất hiện riêng trên trang đó (ví dụ: hiệu ứng thấu kính hội tụ khi chạm ảnh, hay thanh đo âm lượng tương tác theo tốc độ cuộn).
• **Danh mục cấm tuyệt đối (The Refuse List):** Cấm lưới thẻ tính năng giống hệt nhau, cấm bộ đếm `01 / 06` vô nghĩa, cấm văn bản chuyển màu tím AI (AI-purple gradients), và cấm bảng màu đồng/kem mòn mỏi.

scroll-craft không chỉ viết code, nó bắt buộc AI phải lên kịch bản tâm lý học trước khi gõ dòng HTML đầu tiên:

1. **Đường cong cảm xúc (Feeling Curve):** Mỗi phân đoạn (Act) phải gắn liền với một trạng thái cảm xúc cụ thể của người xem. Nếu hai phân đoạn liền kề có cảm xúc giống nhau, một trong hai bị coi là rác thừa và phải bị loại bỏ.
2. **Duy nhất một đỉnh cao trào (The Engineered Peak):** Áp dụng quy tắc Đỉnh - Kết (Peak-End Rule). Chỉ một phần duy nhất trên toàn trang được nhận ngân sách tài nguyên lớn nhất và không gian cuộn dài nhất. Một trang có 3 đỉnh cao trào thực chất là trang không có đỉnh nào.
3. **Quy chuẩn kiểu chữ (Typography Floor):** Tối đa 2 họ font chữ, độ dài dòng khắt khe từ 45 đến 75 ký tự, khoảng cách chữ (tracking) tự động siết chặt khi kích thước font tăng dần.
4. **Hệ thống khoảng trắng (Spacing Rhythm):** Dựa trên hệ số 4px, khoảng trống phía trên tiêu đề luôn lớn hơn phía dưới để phân định khối tự nhiên.
5. **5 Lớp chiều sâu không gian (Depth):** Kết hợp đồng thời bóng đổ lệch (offset shadows), viền sáng cạnh (edge light), tỷ lệ làm mờ theo khoảng cách (scale-and-blur), lớp phủ đè (overlap) và hạt nhiễu điện ảnh (grain).

Sau khi hoàn thành mã nguồn, scroll-craft không dựa vào cảm tính để đánh giá. Một phiên bản trình duyệt không đầu (Headless Chromium thông qua Playwright) sẽ tự động duyệt qua từng nấc cuộn trên trang và kiểm tra:

• **Cuộn chết (Dead Scroll):** Phát hiện những khoảng cuộn mà màn hình không có bất kỳ phản hồi hoặc biến đổi thị giác nào.
• **Chữ mờ vĩnh viễn (Incomplete Opacity):** Tìm kiếm các đoạn văn bản bị lỗi animation khiến độ mờ (opacity) không bao giờ đạt mức 100%.
• **Đo lường độ tương phản thực tế từng dòng:** Đo màu chữ trên nền video/ảnh thực tế tại khung hình sáng nhất lướt qua dưới nó để bảo đảm chuẩn tương phản WCAG.
• **Video bị treo khung hình (Stuck Poster):** Phát hiện các video bị lỗi giải mã trên trình duyệt, tránh sự cố trông như một bức ảnh tĩnh bị đóng băng.

Bảng ảnh tổng kết (Contact Sheet) Hệ thống tự động chụp ảnh màn hình ở từng mốc cuộn và ghép thành một Contact Sheet tổng quan, giúp lập trình viên nhìn thấy toàn bộ hành trình câu chuyện chỉ trong một cái nhìn.

scroll-craft được đóng gói để tương thích tối đa với các môi trường lập trình AI hàng đầu hiện nay:

Đối với OpenAI Codex, Antigravity hoặc các công cụ dòng lệnh khác:

Chạy lệnh doctor trước tiên Lệnh `doctor.mjs` sẽ kiểm tra phiên bản FFmpeg và thư viện Playwright trên máy bạn. Đây là bước quan trọng nhất để tránh các lỗi mã hóa video ngầm trong quá trình tạo hiệu ứng scrubbing.

Quy trình chuẩn mực để xây dựng một website scrollytelling cùng AI thông qua scroll-craft diễn ra qua 5 bước nghiêm ngặt:

1. **Bước 1: Tiếp nhận Brief & Định hình thế giới:** Xác định thương hiệu, thông điệp cốt lõi và lựa chọn 1 trong 8 hệ Ngữ pháp trang (Grammar).
2. **Bước 2: Đối soát Fingerprint Gate:** Kiểm tra với tệp `FINGERPRINTS.md` để chắc chắn thiết kế mới không sao chép lại bố cục của các trang trước đó.
3. **Bước 3: Lập biểu đồ cảm xúc (Feeling Curve):** Xác định duy nhất 1 đỉnh cao trào (The Peak) và lên kịch bản trạng thái cho từng hồi.
4. **Bước 4: Sinh mã & Lắp ráp Engine:** Tạo mã HTML ngữ nghĩa, thiết lập 6 token màu sắc và kết nối thuộc tính cuộn `--sc-p` với chuyển động.
5. **Bước 5: Kiểm định tự động (Verification):** Chạy script Playwright chụp ảnh toàn trang, đo tương phản và xuất bản sản phẩm hoàn thiện.

Một số băn khoăn phổ biến khi ứng dụng scroll-craft vào các dự án thương mại thực tế:

• **Website xây dựng bằng scroll-craft có bị nặng máy hay giật lag không?** Không. Engine sử dụng chuyển động dựa trên CSS Transform và thuộc tính CSS Custom Property kết hợp requestAnimationFrame, đạt chuẩn 60fps mượt mà.
• **Có tốn chi phí API để sinh video không?** Không bắt buộc. Bạn hoàn toàn có thể sử dụng hình ảnh và video quay thật của thương hiệu để làm tài nguyên (tốn đúng 0 USD). API sinh video bằng AI chỉ là tùy chọn mở rộng.
• **Hiển thị trên điện thoại di động có bị vỡ bố cục không?** scroll-craft quy định thiết kế riêng cho mobile: các lớp chiều sâu và video scrubbing được điều chỉnh để tương thích hoàn hảo với thao tác vuốt ngón tay trên màn hình cảm ứng.

Một website xuất sắc không phải là nơi nhồi nhét thật nhiều hiệu ứng, mà là nơi mỗi pixel cuộn chuột đều dẫn dắt người xem qua một trải nghiệm cảm xúc có chủ đích.