ckm:design-system

Tổng quan

ckm:design-system là gì?

ckm:design-system là một kỹ năng design-system kết hợp kiến trúc design token, đặc tả component và tạo slide thuyết trình thành một quy trình thống nhất, có thể tái sử dụng.

Kỹ năng này xoay quanh mô hình token ba lớp (primitive → semantic → component), kèm các tài liệu tham chiếu và script hỗ trợ cho:

• Hệ thống biến CSS
• Thang đo spacing và typography
• Trạng thái và biến thể component
• Cấu hình theme Tailwind
• Bố cục slide và pitch deck có hệ thống

Kỹ năng đi kèm các bảng dữ liệu và template có quan điểm rõ ràng cho nền slide, logic màu sắc, công thức nội dung, bố cục và chiến lược narrative, cùng các script để tạo và kiểm tra token và cấu trúc slide.

Kỹ năng này dành cho ai?

ckm:design-system phù hợp với:

• Lead design-system và nhà thiết kế UI/UX muốn có kiến trúc token rõ ràng và bộ tham chiếu đặc tả component.
• Lập trình viên frontend và React/Tailwind cần một pipeline token vững chắc (biến CSS, công cụ kiểm tra, gợi ý tích hợp Tailwind).
• Founder, PM và marketer thường xuyên làm pitch deck và muốn khung slide lặp lại, nhất quán thương hiệu thay vì phải bắt đầu lại mỗi lần.

Nếu bạn muốn nối liền tư duy thiết kế kiểu Figma với token sẵn sàng triển khai và một hệ thống slide có thể tái sử dụng, kỹ năng này là một lựa chọn rất phù hợp.

ckm:design-system giải quyết những vấn đề gì?

ckm:design-system giúp bạn:

• Chuẩn hóa design tokens với mô hình có tài liệu rõ ràng: primitive → semantic → component.
• Tạo CSS tokens từ JSON và kiểm tra việc sử dụng chúng trong codebase.
• Lên kế hoạch cho theme Tailwind dựa trên cùng kiến trúc token.
• Định nghĩa đặc tả component bao gồm trạng thái và biến thể để UI nhất quán trên mọi màn hình.
• Thiết kế slide nhất quán thương hiệu bằng các layout slide có sẵn, gợi ý chart, logic màu sắc & cảm xúc, và công thức nội dung.

Kỹ năng này cho bạn một cách tiếp cận có cấu trúc để xem cả UI lẫn slide như các hệ thống, không phải những sản phẩm đơn lẻ.

Khi nào nên dùng ckm:design-system?

Hãy dùng kỹ năng này khi:

• Bạn đang giới thiệu hoặc refactor một design system và muốn các lớp token rõ ràng.
• Bạn cần hướng dẫn về biến CSS và Tailwind gắn chặt với kiến trúc token.
• Bạn muốn tạo và kiểm tra design tokens thay vì tự quản lý thủ công.
• Bạn thường xuyên làm pitch deck, sales presentation hoặc product demo và cần cấu trúc slide có thể lặp lại.

Kỹ năng này ít phù hợp nếu bạn chỉ cần một bản mock UI tĩnh duy nhất, hoặc hoàn toàn không sử dụng token hay biến CSS.

Cách sử dụng

Cài đặt và thiết lập cơ bản

1. Cài đặt kỹ năng ckm:design-system

Cài kỹ năng vào môi trường Agent/skills của bạn:

npx skills add https://github.com/nextlevelbuilder/ui-ux-pro-max-skill --skill design-system

Lệnh này lấy kỹ năng design-system từ repository nextlevelbuilder/ui-ux-pro-max-skill về thư mục skills cục bộ của bạn.

2. Khám phá các file cốt lõi

Sau khi cài đặt, mở thư mục skill và bắt đầu với:

• SKILL.md – Tổng quan cấp cao, khi nào nên dùng skill, kiến trúc token và các lệnh khởi động nhanh.
• references/ – Tài liệu khái niệm cho tokens, components, variants và tích hợp Tailwind.
• data/ – Các file CSV mã hóa nền slide, logic màu sắc, công thức nội dung, bố cục, typography và chiến lược.
• scripts/ – Script tiện ích để tạo, embed và kiểm tra token, cùng công cụ hỗ trợ tìm slide.
• templates/design-tokens-starter.json – Template JSON khởi điểm để định nghĩa bộ token của riêng bạn.

Cấu trúc này giúp bạn nhanh chóng quyết định phần nào sẽ áp dụng: chỉ token, chỉ slide, hay cả hệ thống.

Thiết kế kiến trúc token của bạn

3. Hiểu mô hình token ba lớp

SKILL.md và references/token-architecture.md mô tả cấu trúc ba bước:

Primitive (raw values)
       ↓
Semantic (purpose aliases)
       ↓
Component (component-specific)

Dùng các file tham chiếu để thiết kế từng lớp:

• references/primitive-tokens.md – Màu cơ bản, spacing, radii, typography primitives.
• references/semantic-tokens.md – Token theo mục đích như --color-primary, --surface-elevated, --text-muted.
• references/component-tokens.md – Biến ở cấp component như --button-bg, --card-border, --badge-pill-radius.

Sự tách bạch này giúp bạn:

• Đổi theme mà không phải viết lại component.
• Giữ chi tiết triển khai (biến CSS, cấu hình Tailwind) luôn khớp với ngôn ngữ thiết kế.

4. Tạo mới hoặc điều chỉnh token JSON

Dùng templates/design-tokens-starter.json làm nền cho file token của bạn.

Quy trình điển hình:

1. Copy templates/design-tokens-starter.json vào project thành tokens.json.
2. Điền các giá trị primitive trước (màu, spacing, cỡ font).
3. Map primitive sang các vai trò semantic (primary, secondary, surface, border, v.v.).
4. Map semantic tokens sang component tokens cho từng thành phần UI chính.

Tham khảo thêm:

• references/component-specs.md – Cách thinking về việc component tiêu thụ token.
• references/states-and-variants.md – Cho trạng thái hover, focus, disabled, error và các biến thể.

Tạo và kiểm tra tokens

5. Tạo biến CSS từ tokens

Dùng script tạo token được mô tả trong SKILL.md:

node scripts/generate-tokens.cjs --config tokens.json -o tokens.css

• --config trỏ tới file token JSON (vd: tokens.json).
• -o đặt tên file CSS đầu ra (vd: tokens.css).

Kết quả là một file CSS định nghĩa bộ token của bạn dưới dạng --custom-properties, sẵn sàng import vào frontend.

6. Kiểm tra việc sử dụng token trong codebase

Để đảm bảo code chỉ dùng các token đã được phê duyệt, chạy validator token:

node scripts/validate-tokens.cjs --dir src/

Lệnh này kiểm tra thư mục được chỉ định (vd: src/) để tìm pattern sử dụng token và giúp bạn:

• Bắt các giá trị hard-code lẽ ra nên dùng token.
• Phát hiện token đã deprecated hoặc chưa được định nghĩa.

Các validator bổ sung trong scripts/ gồm:

• html-token-validator.py – Quét HTML để tìm pattern sử dụng token.
• slide-token-validator.py – Kiểm tra việc dùng token trong ngữ cảnh slide.

Dùng các script này để giữ cho UI và slide luôn bám sát design system.

7. Embed tokens vào nơi cần thiết

Nếu môi trường của bạn cần embed token vào tài liệu hoặc HTML, bạn có thể dùng:

• scripts/embed-tokens.cjs – Embed token vào các file mục tiêu.

Xem comment trong script và SKILL.md để biết hướng dẫn sử dụng cụ thể cho setup của bạn.

Tailwind và các lưu ý triển khai

8. Lên kế hoạch tích hợp Tailwind

Kỹ năng này bao gồm một tài liệu riêng cho Tailwind:

• references/tailwind-integration.md – Hướng dẫn map tên và thang token sang cấu hình theme Tailwind.

Dùng tài liệu này để:

• Map primitive/semantic tokens vào các thang colors, spacing, fontSize của Tailwind.
• Giữ các utility class của Tailwind đồng bộ với thiết kế token (vd: palette primary được dẫn xuất từ primitives).

Ngay cả khi chưa dùng Tailwind, tài liệu này vẫn hữu ích để bạn hình dung cách hệ thống token mở rộng sang utility-first CSS.

Xây dựng pitch deck có hệ thống

Mặc dù danh mục chính là design system, ckm:design-system cũng hỗ trợ thiết kế slide trình bày có cấu trúc.

9. Dùng bảng dữ liệu slide cho layout và hình ảnh

Thư mục data/ chứa các file CSV mã hóa các pattern slide theo best-practice:

• data/slide-backgrounds.csv – Loại ảnh nền khuyến nghị, lớp phủ (overlay) và cách đặt ảnh theo từng loại slide (hero, vision, team, testimonial, CTA, problem, solution, v.v.).
• data/slide-color-logic.csv – Cách các cảm xúc (frustration, hope, fear, relief, trust, urgency, curiosity, v.v.) map sang kiểu nền, màu chữ và cách dùng màu nhấn.
• data/slide-typography.csv – Hướng dẫn typography theo loại slide (thứ bậc, nhấn mạnh, v.v.).
• data/slide-layout-logic.csv – Pattern bố cục dựa trên mục tiêu narrative và cảm xúc (hook, problem, solution, proof, traction, CTA, timeline, features, v.v.).
• data/slide-layouts.csv – Pattern bố cục cụ thể kèm gợi ý cấu trúc CSS (vd: grid, split layout, hero layout, gợi ý animation).

Bạn có thể nạp các bảng này vào pipeline riêng (script, spreadsheet hoặc deck generator) để tạo slide nhất quán, được dẫn dắt bởi narrative và cảm xúc thay vì quyết định thiết kế ngẫu hứng.

10. Cấu trúc nội dung slide bằng các công thức đã được kiểm chứng

data/slide-copy.csv cung cấp các công thức copywriting phù hợp với nhiều loại slide, bao gồm:

• AIDA (Attention → Interest → Desire → Action)
• PAS (Problem → Agitate → Solution)
• 4Ps (Promise → Picture → Proof → Push)
• Before-After-Bridge
• QUEST
• Star-Story-Solution

Mỗi dòng gồm:

• formula_name và keywords
• Các components được cấu trúc
• use_case và example_template
• emotion_trigger và slide_type

Bạn có thể dùng chúng để:

• Yêu cầu một agent soạn nội dung slide theo công thức cụ thể.
• Chuẩn hóa nội dung giữa các pitch deck và sales presentation.

11. Chọn chiến lược slide cho trọn bộ deck

data/slide-strategies.csv định nghĩa các pattern deck hoàn chỉnh, ví dụ:

• YC Seed Deck
• Guy Kawasaki 10/20/30
• Series A Deck

Mỗi chiến lược bao gồm:

• Số lượng slide khuyến nghị
• Trình tự (title, problem, solution, traction, market, v.v.)
• Mục tiêu, đối tượng và tone
• Arc narrative và cảm xúc

Nhờ đó bạn có thể:

• Tạo outline slide hoàn chỉnh cho chiến lược đã chọn.
• Giữ design system và cấu trúc câu chuyện luôn đi cùng nhau.

12. Làm việc với các script slide

Thư mục scripts/ chứa các tiện ích phục vụ workflow slide:

• scripts/generate-slide.py – Logic tạo slide cốt lõi (bạn có thể chỉnh sửa để tích hợp vào deck generator hoặc pipeline riêng).
• scripts/search-slides.py và scripts/slide_search_core.py – Công cụ tìm kiếm giúp bạn tra cứu pattern hoặc chiến lược slide phù hợp theo keyword và ngữ cảnh.
• scripts/fetch-background.py – Giúp lấy ảnh nền (vd: từ Pexels/Unsplash) dựa trên guideline trong data/slide-backgrounds.csv.

Các script này là những khối xây dựng cơ bản. Bạn có thể chạy hoặc chỉnh sửa chúng tùy theo môi trường và nhu cầu tự động hóa.

Làm việc với tài liệu tham chiếu

13. Dùng tài liệu làm checklist triển khai

Thư mục references/ không chỉ là tài liệu; nó còn hoạt động như checklist khi bạn xây dựng design system:

• references/token-architecture.md – Xác nhận lớp primitive/semantic/component của bạn đã hợp lý.
• references/primitive-tokens.md – Đảm bảo bạn có bộ token cơ bản đầy đủ.
• references/semantic-tokens.md – Kiểm tra mỗi semantic token đều có mục đích rõ ràng.
• references/component-tokens.md – Map token vào các component thực tế.
• references/component-specs.md – Ghi lại trạng thái, biến thể, tương tác và các cân nhắc về accessibility.
• references/states-and-variants.md – Tránh sót các trạng thái hover, focus, active, disabled, error, success.

Hãy dùng các file này trong quá trình design review và handoff để giữ designer và developer luôn đồng bộ.

Tùy biến kỹ năng cho stack của bạn

14. Tích hợp từng bước

Bạn không cần áp dụng toàn bộ kỹ năng ngay từ đầu. Một số cách triển khai dần dần phổ biến:

• Chỉ dùng token – Bắt đầu với templates/design-tokens-starter.json, generate-tokens.cjs và validate-tokens.cjs để dựng pipeline token.
• Chỉ dùng slide – Dùng các file CSV trong data/ và scripts/generate-slide.py để chuẩn hóa slide mà vẫn giữ nguyên design system hiện tại.
• Dùng toàn bộ hệ thống – Kết hợp token, component và cấu trúc slide để xây dựng hệ thống thương hiệu thống nhất cho cả product UI và pitch deck.

Hãy tập trung trước vào phần giải quyết vấn đề cấp bách nhất của bạn, rồi mở rộng dần.

FAQ

ckm:design-system là UI kit hay engine design token?

Đây chủ yếu là một kỹ năng design-system và kiến trúc token đi kèm một hệ thống slide có cấu trúc. Nó không cung cấp sẵn UI kit Figma, nhưng cho bạn:

• Kiến trúc token ba lớp
• Script để tạo và kiểm tra token
• Tài liệu tham chiếu cho đặc tả component và trạng thái

Bạn có thể dễ dàng phản chiếu cùng token và component sang Figma hoặc bất kỳ công cụ thiết kế nào khác.

Tôi có thể dùng ckm:design-system mà không cần Tailwind hoặc React không?

Có. Tích hợp Tailwind được mô tả trong references/tailwind-integration.md, nhưng hoàn toàn tùy chọn. Token được tạo dưới dạng biến CSS chuẩn, nên bạn có thể dùng trong bất kỳ stack nào:

• Vanilla CSS hoặc CSS Modules
• Styled-components hoặc các giải pháp CSS-in-JS khác
• Design tokens cho Web Components hoặc framework khác

ckm:design-system giúp gì cho phần trình bày slide?

Kỹ năng này xem slide deck như một bài toán design system:

• data/slide-layouts.csv và data/slide-layout-logic.csv định nghĩa pattern bố cục và cấu trúc CSS.
• data/slide-backgrounds.csv và data/slide-color-logic.csv map loại slide và cảm xúc sang yếu tố thị giác.
• data/slide-copy.csv và data/slide-strategies.csv cung cấp công thức nội dung và cấu trúc deck.
• Các script như generate-slide.py và search-slides.py hỗ trợ tự động hóa việc tạo và truy xuất slide.

Nhờ đó bạn có thể xây dựng những deck lặp lại được, nhất quán với thương hiệu thay vì các slide rời rạc.

Tôi có bắt buộc phải dùng nguyên bộ dữ liệu CSV không?

Không. Các file CSV là những mặc định có quan điểm rõ ràng. Bạn có thể:

• Dùng nguyên trạng để tạo pitch deck nhanh.
• Fork và tùy biến để phù hợp với giọng thương hiệu và phong cách hình ảnh của bạn.
• Thay thế hoàn toàn bằng dữ liệu riêng nhưng vẫn giữ pattern script tương tự.

Tôi nên bắt đầu từ đâu nếu chỉ quan tâm đến design token?

Nếu bạn tập trung vào token và triển khai UI:

1. Đọc SKILL.md, đặc biệt là phần "When to Use" và "Token Architecture".

2. Mở references/token-architecture.md cùng các tài liệu primitive/semantic/component token.

3. Copy templates/design-tokens-starter.json và tạo tokens.json của bạn.

4. Chạy:

   node scripts/generate-tokens.cjs --config tokens.json -o tokens.css
   node scripts/validate-tokens.cjs --dir src/
   

Như vậy bạn đã có một pipeline token hoạt động mà chưa cần đụng đến hệ thống slide.

ckm:design-system có phù hợp với project nhỏ không?

Có thể, nhưng sức mạnh của nó thể hiện rõ hơn trong các project mà:

• Nhiều người cùng tham gia vào UI hoặc deck
• Tính nhất quán và khả năng mở rộng rất quan trọng
• Bạn dự kiến sẽ lặp lại và phát triển thương hiệu hoặc sản phẩm theo thời gian

Với một landing page đơn lẻ hoặc một bài thuyết trình nội bộ, toàn bộ hệ thống có thể hơi “dư cấu trúc”. Bạn vẫn có thể mượn kiến trúc token hoặc công thức slide như những guideline nhẹ nhàng.

Làm sao để xem đầy đủ mọi thứ có trong skill?

Trong trình duyệt skills hoặc file explorer, hãy xem toàn bộ tree của skill design-system, đặc biệt là:

• SKILL.md
• data/
• references/
• scripts/
• templates/design-tokens-starter.json

Điều này sẽ cho bạn thấy tất cả tài liệu tham chiếu lồng nhau và các script hỗ trợ, để quyết định phần nào sẽ tích hợp vào workflow của riêng bạn.