Website không dùng mẫu với Claude Code và Refero DESIGN.md

Tài liệu thực hành về cách làm việc với dự án và mô hình: tài liệu Ailoot.

Vì sao website Claude Code trông giống mẫu Tailwind?#

Trong ví dụ tháng Một được mô tả, một dự án phụ nhỏ đang được tạo ra — một công cụ gọi điện bán hàng cho khách hàng lạnh. Trong một kho mã trống, Claude Code được yêu cầu xây dựng trang chủ. Kết quả rất đại trà: nền tối slate-950, màu nhấn purple-500, tiêu đề đậm dùng phông sans-serif và ba thẻ bên dưới có bóng đổ giống nhau. Bố cục giống hệt phiên bản đầu tiên của ChatGPT, phiên bản đầu tiên của Lovable và phiên bản đầu tiên của v0. Sau năm lần chỉnh sửa prompt, thêm các từ “hiện đại”, “cao cấp” và “không giống ai khác” — mọi thứ vẫn vậy. Trang vẫn trông như được lấy từ một bộ Tailwind UI Templates.

Nói cách khác, Claude không phải “không biết” cách tạo ra thứ gì đó đẹp. Nó biết đa số mọi người làm gì và tái tạo lại phần đa số đó. Muốn có kết quả không bị trung bình hóa, tác nhân cần những ràng buộc cụ thể: dùng màu nào, phông chữ nào, khoảng cách ra sao và thành phần nào cần được coi là chuẩn.

Đó là lúc hệ thống thiết kế trở thành bối cảnh. Không phải “hãy làm cho đẹp”, mà là “hãy làm theo phong cách cụ thể này; đây là các thông số của nó”.

Refero Styles thu hẹp khoảng cách đó bằng một sản phẩm có sẵn — tệp DESIGN.md chứa các thông số từ những sản phẩm thực tế.

Refero Styles là gì?#

Trang chủ styles.refero.design mô tả rõ ràng: “khám phá hơn 2.000 hệ thống thiết kế từ các website sản phẩm hàng đầu, có thể đọc được bằng tác nhân AI”. Danh mục có những thương hiệu đặt ra tiêu chuẩn thị giác: Apple, Linear, Stripe, Notion, Vercel, ElevenLabs, Mercury, PostHog, xAI, Modal, Duolingo. Các hệ thống này không được trích xuất thủ công — nhóm Refero chạy một script phân tích CSS và markup thực tế của website, rồi đóng gói kết quả thành markdown có cấu trúc. Thư viện styles.refero.design hoàn toàn miễn phí.

Từ khóa là “có cấu trúc”. Tệp không chứa ảnh chụp màn hình hay mô tả kiểu “theo phong cách tối giản”. Đó là markdown với các mã màu hex cụ thể, cỡ chữ chính xác theo pt, đơn vị khoảng cách và quy tắc cho các thành phần. Tác nhân AI đọc tệp và làm việc với thông tin cụ thể thay vì cố mô tả gu thẩm mỹ bằng lời.

Trong trang ai-agents, nhóm Refero liệt kê các công cụ được hỗ trợ là “Cursor, Claude Code, Codex, v0 và Lovable”. Nói cách khác, DESIGN.md là một sản phẩm dùng chung — một tệp phù hợp với tất cả các tác nhân phát triển AI lớn.

DESIGN.md có những gì?#

Nhóm Refero mô tả cấu trúc tệp trên trang design-md-template như sau:

Vì vậy, cấu trúc tệp thường trông như sau:

Những người tạo ra hệ thống cũng nhấn mạnh một nguyên tắc giải quyết 80% vấn đề thiết kế AI:

Nói cách khác, mã hex #5E6AD2 có sức nặng hơn “giống Linear”. Giá trị chính xác font-size: 13px / line-height: 18px cụ thể hơn “văn bản gọn”. Thông tin cụ thể hiệu quả hơn cách diễn giải.

DESIGN.md trong kho mã không phải là hình ảnh cho nhóm xem. Nó là một khối xây dựng trong bối cảnh lâu dài của dự án: kiến thức có cấu trúc mà AI đọc trong mỗi yêu cầu.

Cách tạo website theo phong cách Linear trong 4 bước#

Bốn bước này tạo thành trình tự được mô tả để bắt đầu một website mới. Không phải “bốn bước nói chung”, mà là trình tự cụ thể với một hành động cho mỗi bước.

1. Cài Claude Code

   Trình cài đặt gốc với một lệnh: curl -fsSL https://claude.ai/install.sh | bash (phương pháp được khuyến nghị trong tài liệu chính thức). Trên macOS, brew install --cask claude-code cũng hoạt động; trên Windows dùng winget install Anthropic.ClaudeCode. Nếu đã cài đặt, hãy kiểm tra phiên bản: claude --version (cần phiên bản 2.1.178 trở lên — phiên bản này giới thiệu quyền Tool(param:value) và chặn các lệnh git nguy hiểm trong chế độ tự động). Đăng nhập vào tài khoản: claude sẽ mở trình hướng dẫn. Claude Code được bao gồm trong gói Pro ($17/tháng nếu thanh toán theo năm hoặc $20/tháng nếu thanh toán theo tháng).

2. Mở Refero Styles và chọn thương hiệu

   Truy cập https://styles.refero.design và mở danh mục. Tiêu chí lựa chọn chính là mức độ phù hợp với sản phẩm của bạn, không phải bạn có “thích giao diện đó hay không”. Đang xây dựng bảng điều khiển SaaS? Hãy xem Linear, Vercel và Notion. Đang xây dựng sản phẩm fintech? Hãy xem Stripe, Mercury và Column. Đang xây dựng sản phẩm dành cho thành viên? Hãy xem Duolingo. Mở thẻ thương hiệu rồi nhấp vào “Copy DESIGN.md”.

3. Đưa DESIGN.md vào dự án làm bối cảnh

   Tạo tệp docs/DESIGN.md ở thư mục gốc của dự án và dán nội dung đã sao chép vào đó. Sau đó mở CLAUDE.md và thêm một dòng: @docs/DESIGN.md. Đây là chỉ thị nhập — Claude Code tải nội dung vào bối cảnh khi một phiên bắt đầu. Để biết thêm về việc nhập trong CLAUDE.md, xem hướng dẫn về một tệp chỉ dẫn cho Claude Code, Codex và Cursor.

4. Yêu cầu một trang cụ thể

   Đừng nói “làm cho đẹp”. Hãy nói cụ thể: “Dựa trên DESIGN.md trong bối cảnh, hãy xây dựng trang chủ cho sản phẩm quản lý nhiệm vụ SaaS. Cấu trúc: hero với tiêu đề và tiêu đề phụ, hai nút CTA (chính và phụ), bên dưới là một khối gồm 3 tính năng và biểu tượng, tiếp đến là khối lời chứng thực. Dùng chính xác màu sắc và kiểu chữ trong DESIGN.md; đừng tự nghĩ ra thông số.”

Sau bước thứ tư, Claude sẽ dựng trang. Trong trải nghiệm được mô tả, một trang chủ mất trung bình 8–12 phút — và thực sự trông gần với phong cách của thương hiệu đã chọn. Không phải bản sao chính xác đến từng pixel, nhưng có thẩm mỹ dễ nhận ra: cùng phông chữ, cùng bảng màu, cùng nhịp điệu khoảng cách và cùng những quyết định nhỏ ở các nút.

Những người tạo Refero mô tả ngắn gọn hơn nguyên tắc ba bước tương tự trên trang ai-agents/design-resources:

Trình tự bốn bước này theo cùng logic, đồng thời nêu rõ thêm các bước cài Claude Code và nhập tệp vào CLAUDE.md.

Nên chọn phong cách nào cho sản phẩm của bạn?#

Những người tạo Refero đưa ra lời khuyên này ngay ở bước đầu tiên trong hướng dẫn: chọn mẫu tham chiếu không chỉ dựa vào tên thương hiệu mà còn dựa vào mật độ thông tin, sắc thái và đối tượng người dùng.

Màu, kiểu chữ, phân cấp và chuyển động tiết chế theo Apple có thể hợp dashboard SaaS, nhưng spacing rộng của một trang marketing cụ thể có thể không hợp. Xem đúng tham chiếu thay vì chọn theo thương hiệu. Dashboard kế toán cần quy định chiều cao dòng, spacing và mật độ gọn, giữ số và điều khiển đọc được; không chép nguyên bố cục thuyết trình rộng.

Hướng dẫn đơn giản để chọn theo loại sản phẩm:

Nếu vẫn phân vân, hãy chọn Linear. Nền tảng này linh hoạt hơn cả: bảng màu trung tính, kiểu chữ dễ đọc (Inter / Söhne) và khoảng cách vừa phải. Một website dựa trên Linear sẽ trông chuyên nghiệp với 9 trên 10 loại sản phẩm.

Vì sao nên đưa DESIGN.md vào bối cảnh lâu dài của dự án?#

Trong thực tiễn được mô tả, DESIGN.md được lưu bên cạnh CLAUDE.md trong mọi dự án do các tác nhân AI quản lý. Tệp này không được coi là “tạm thời cho một nhiệm vụ”. Đây là chuẩn cố định mà mọi phiên làm việc về sau dựa vào. Một tháng sau, bạn có thể yêu cầu Claude thêm trang mới vào dự án — nó sẽ mở đúng DESIGN.md đó và xây dựng theo cùng phong cách. Sáu tháng sau, bạn có thể bàn giao dự án cho một thành viên nhóm khác — họ cũng có thể chạy Claude và nhận kết quả nhất quán vì DESIGN.md nằm trong kho mã.

Trong thiết kế, nguyên tắc này hoạt động như sau: chỉ cần quyết định một lần về bảng màu, kiểu chữ và nhịp điệu khoảng cách. Sau đó, mọi tác nhân AI đều xem đó là điều đã được xác định.

Nghĩa là thiết kế tồn tại dưới dạng mã (markdown là mã), chứ không phải tệp Figma mà AI không thể đọc. Khi thiết kế là một tệp trong kho mã, Claude Code đọc được, Codex đọc được và mọi công cụ tương lai đều có thể đọc. Khi thiết kế nằm trong Figma, nó ở một không gian riêng và phải được chuyển thành mô tả thủ công trong mỗi phiên.

Trong các dự án phụ được mô tả, cấu trúc sau đã được sử dụng:

project/
├── CLAUDE.md            (imports @docs/DESIGN.md)
├── docs/
│   ├── DESIGN.md        (visual canon, copied from Refero)
│   ├── ARCHITECTURE.md  (project structure)
│   └── BRAND.md         (tone of voice, vocabulary)
└── ...

Ba tệp này là một cách tổ chức bối cảnh lâu dài của dự án. DESIGN.md phụ trách hình ảnh, ARCHITECTURE.md phụ trách cấu trúc và BRAND.md phụ trách giọng văn. Bất kỳ tác nhân AI nào có quyền truy cập vào kho mã đều nhận được cả ba làm bối cảnh.

Refero MCP và refero_skill là gì?#

Refero Styles là lớp nền (DESIGN.md dưới dạng tệp). Làn sóng tiếp theo là các tích hợp giúp tác nhân AI truy cập thư viện một cách “native”.

Refero MCP (chính thức). Đây là API máy chủ tại https://api.refero.design/mcp, nơi Claude Code kết nối bằng bearer token. Sau đó, tác nhân có thể truy cập hơn 150.000 màn hình và hơn 6.000 luồng người dùng từ các sản phẩm thực tế. Có thể cài đặt bằng skill:

npx skills add https://github.com/referodesign/refero_skill --skill refero-design

Sau khi cài đặt, Claude khởi chạy “nghiên cứu thiết kế” vào đầu mỗi phiên như một bước bắt buộc đầu tiên: công cụ xem xét lựa chọn thị giác nào phù hợp với nhiệm vụ và nếu cần sẽ đề xuất ba hướng gắn với mẫu tham chiếu đã chọn. Tính đến ngày 23 tháng 6 năm 2026, kho refero_skill có 67 commits và 135 stars. Đây là sản phẩm mới đang được phát triển tích cực.

Cách làm được mô tả ở đây rất đơn giản: tự mở website, sao chép DESIGN.md rồi đưa vào tệp. MCP hữu ích khi việc làm việc với hệ thống thiết kế trở thành công việc thường xuyên — chẳng hạn khi quản lý nhiều dự án khách hàng và chuyển đổi giữa các chuẩn thị giác mỗi ngày. Tìm hiểu thêm về cách kết nối máy chủ MCP với Claude Code trong hướng dẫn về NotebookLM và MCP.

4 lỗi nào làm hỏng quy trình này?#

Bốn lỗi này thường lặp lại trong trải nghiệm làm việc với bối cảnh thiết kế được mô tả. Mỗi lỗi có vẻ vô hại, nhưng đều đưa kết quả trở lại mẫu Tailwind tiêu chuẩn.

Lỗi 1. Prompt “làm cho trông hiện đại”. Đây là kiểu sai lầm phổ biến nhất. Mọi người mở Claude Code và viết: “làm cho tôi một website SaaS, phong cách hiện đại, vẻ ngoài cao cấp”. Họ nhận được nền tối cùng màu nhấn tím. Trong dữ liệu huấn luyện, từ “hiện đại” gắn với mọi trang đích giai đoạn 2022–2024 được dựng từ cùng một mẫu. Không có các thông số chính xác từ DESIGN.md, “hiện đại” có nghĩa là “trung bình”.

Lỗi 2. Dán DESIGN.md vào chat như một tin nhắn. Đôi khi mọi người sao chép DESIGN.md vào cửa sổ chat Claude Code rồi nói: “đây là phong cách, hãy dùng nó”. Cách này chỉ hiệu quả một lần — cho đến khi phiên làm việc kết thúc. Mở phiên mới (hoặc chuyển sang nhiệm vụ khác, /clear), bối cảnh sẽ mất. Muốn phong cách được giữ lại, tệp phải nằm trong kho mã và được nhập qua CLAUDE.md. Đọc thêm về lý do CLAUDE.md là điểm tựa cho bối cảnh lâu dài trong hướng dẫn về bộ nhớ Claude.

Lỗi 3. Chọn phong cách vì “mình thích”. Tham chiếu marketing Apple rộng có thể không hợp để chép nguyên vào dashboard bất động sản cần 30 tin trên màn. Điều đó không loại kiểu chữ, palette, phân cấp theo Apple: điều chỉnh spacing và mật độ dòng theo việc rồi kiểm lượng thông tin thấy ở kích thước màn đích. Chọn tham chiếu cụ thể theo mật độ, sắc thái, đối tượng, không chỉ tên thương hiệu.

Lỗi 4. Không nhắc đến DESIGN.md ngay trong prompt. DESIGN.md có thể nằm trong kho mã, được nhập qua CLAUDE.md và hiển thị với tác nhân. Nhưng nếu prompt chỉ nói “xây dựng một website”, Claude có thể chọn cách làm tiêu chuẩn mà không tham chiếu rõ tệp. Với mọi prompt thiết kế, câu này sẽ hữu ích: “Dùng chính xác màu sắc, phông chữ và khoảng cách từ docs/DESIGN.md. Đừng tự nghĩ ra giá trị; hãy lấy chúng từ tệp.” Câu này đảm bảo tác nhân dùng DESIGN.md thay vì bỏ qua nó.

Token chính xác là mã hex, cỡ chữ theo pt và đơn vị khoảng cách trong DESIGN.md. Ngôn ngữ tự nhiên là “hiện đại”, “cao cấp”, “gọn gàng” hoặc “giống Apple”. Token chính xác có hiệu quả; từ ngữ chung chung thì không.

Tiếp theo nên làm gì?#

Giờ bạn đã có quy trình cơ bản: Claude Code + DESIGN.md từ Refero + 4 bước = website không dùng mẫu. Quy trình này đáp ứng 70% nhu cầu. 30% còn lại là những trường hợp cần độ chính xác cao hơn, tốc độ nhanh hơn hoặc xác minh.

Ba hướng nên tiếp tục sau khi đã nắm vững phần cơ bản:

1. Frontend Design Skill. Đây là skill chính thức cho Claude Code, bổ sung phản hồi trực quan. Tác nhân chụp ảnh màn hình trang đã dựng bằng Puppeteer, quan sát bằng “mắt” của nó (mô hình thị giác), so sánh với DESIGN.md rồi tự đề xuất chỉnh sửa. Đây là vòng lặp tự động “prompt → code → ảnh chụp màn hình → nhận xét → prompt”. Hữu ích khi trang phức tạp và không thể làm đúng chỉ trong một lần lặp.

2. Refero MCP trong chế độ production. Khi quản lý 3–5 dự án cùng lúc, việc tự thêm DESIGN.md cho từng dự án trở nên phiền phức. Refero MCP có thể tìm 3 phong cách phù hợp dựa trên mô tả dự án rồi đưa ra lựa chọn. Công cụ này rút ngắn thời gian bắt đầu dự án mới từ 30 phút xuống còn 3 phút.

3. Kết hợp với Context Engineering. DESIGN.md là một trong các sản phẩm bối cảnh. Bên cạnh đó thường có ARCHITECTURE.md (cấu trúc dự án), BRAND.md (giọng điệu thương hiệu) và business/audience.md (đối tượng mục tiêu). Tất cả được nhập trong CLAUDE.md. Khi Claude dựng một trang, nó dựa vào hình ảnh, đối tượng và cấu trúc sản phẩm. Về cơ bản, đây là context engineering — làm việc có hệ thống với những gì bạn cung cấp cho tác nhân trước một yêu cầu.

Tài liệu thực hành: tài liệu Ailoot.

Tài liệu thực hành: tài liệu Ailoot.

Tài liệu và công cụ khác: Ailoot.