Primer CSS là triển khai CSS chính thức cho hệ thống thiết kế của GitHub — một bộ thư viện giao diện được xây dựng dựa trên nguyên tắc nhất quán, khả năng mở rộng và hỗ trợ truy cập toàn diện. Không chỉ phục vụ giao diện người dùng của github.com, Primer còn được thiết kế để tích hợp linh hoạt vào các ứng dụng web hiện đại thông qua kiến trúc mô-đun và hệ thống biến hóa học rõ ràng.
Cấu trúc kiến trúc phân lớp
Hệ thống được tổ chức thành ba nhóm chức năng chính:
- Core: Cung cấp các thành phần nền tảng như typography, spacing scale, buttons cơ bản, tooltip, và các quy tắc reset.
- Product: Tập trung vào các thành phần đặc thù cho trải nghiệm sản phẩm GitHub — ví dụ: avatar stack, issue labels, markdown-rendered content, và progress bars.
- Marketing: Hỗ trợ các trang tiếp thị với các thành phần như banner responsive, localized call-to-action, và campaign-specific theming.
Nguyên lý thiết kế cốt lõi
Primer áp dụng mô hình utility-first kết hợp với component abstraction. Mỗi class CSS có phạm vi tác động hẹp và không chồng chéo — ví dụ: d-flex chỉ điều khiển display, border-2 chỉ xử lý độ dày viền. Các thành phần phức tạp (như <details-dialog>) được đóng gói dưới dạng custom elements hoặc SCSS mixins để đảm bảo tính tái sử dụng cao.
Hệ thống khoảng cách và kiểu chữ
Primer sử dụng thang đo khoảng cách dựa trên bội số của 8px, từ 1 (8px) đến 6 (48px), với các tiền tố m-, p-, mx-, my-. Kiểu chữ được định nghĩa theo hệ thống type scale gồm 6 mức kích thước (f1–f6), mỗi mức đi kèm line-height tối ưu và font-weight phù hợp với vai trò ngữ nghĩa.
Quản lý chủ đề và chế độ màu
Hệ thống hỗ trợ nhiều chế độ màu thông qua các tập tin SCSS riêng biệt:
@import "@primer/css/color-modes/themes/light.scss";
@import "@primer/css/color-modes/themes/dark.scss";
@import "@primer/css/color-modes/themes/light_high_contrast.scss";
@import "@primer/css/color-modes/themes/light_colorblind.scss";Mỗi chủ đề định nghĩa lại các biến $color-fg-default, $color-bg-subtle, v.v., đảm bảo tương thích với tiêu chuẩn WCAG 2.1 AA trở lên.
Cách tích hợp trong dự án
Sau khi cài đặt qua npm:
npm install @primer/cssBạn có thể nhập chọn lọc theo nhu cầu:
// Chỉ cần core + buttons
@use "@primer/css/core" as *;
@use "@primer/css/buttons" as *;
// Hoặc nhập toàn bộ (không khuyến khích cho SPA)
@use "@primer/css/index" as *;Các tệp SCSS đều tuân thủ quy ước BEM và sử dụng @use thay vì @import để đảm bảo scope biến và tránh xung đột.
Cơ chế xây dựng và tùy chỉnh
Quy trình build sử dụng sass CLI kết hợp postcss để thêm vendor prefix tự động và tối ưu hóa output. Biến toàn cục được khai báo trong src/variables/, cho phép override dễ dàng trước khi biên dịch — ví dụ: thay đổi giá trị $font-size-2 hoặc $border-radius-2 để điều chỉnh phong cách thương hiệu.
Tài liệu và hỗ trợ phát triển
Tài liệu tương tác được viết bằng MDX và chạy trên Storybook tại docs/stories/. Mỗi thành phần đều có ví dụ thực thi, hướng dẫn sử dụng, và kiểm tra khả năng truy cập (a11y audit). File DEVELOP.md mô tả chi tiết cách khởi tạo môi trường phát triển cục bộ, chạy test CSS, và đóng góp vào kho mã nguồn.