Tasco Framework

Giao diện

Đổi design token ​

Token trong @tasco/theme là nguồn duy nhất của màu, font, bo góc và mật độ cho mọi app. Đổi một giá trị là đổi giao diện của tất cả sản phẩm ở bản phát hành sau — nên làm có kiểm tra, không làm vội.

Token đi đâu ​

packages/theme/src/tokens.ts        ColorTokens, DensityTokens, TascoTokens; lightTokens, darkTokens
        │
        ├─ css-vars.ts      cssVars(mode) → --tasco-* ──▶ style scoped của C*, CSS của app, base.css, docs
        ├─ antd-theme.ts    getAntdTheme(mode) → token toàn cục antdv ──▶ ConfigProvider trong app.vue của layer
        └─ contrast-pairs.ts  cặp chữ/nền cần đạt AA ──▶ test + bảng trong docs
packages/theme/styles/base.css      phần antdv 4 không cấu hình được bằng token (bảng, mật độ, chữ màu ở chế độ tối)
packages/nuxt-layer-base/nuxt.config.ts  fonts.families — font được tự host

Đổi giá trị có sẵn ​

  1. Sửa giá trị trong lightTokens và darkTokens nếu cả hai chế độ cùng đổi.
  2. Chạy pnpm --filter @tasco/theme test — test tương phản báo cặp nào tụt dưới 4.5:1. Không hạ ngưỡng và không thêm knownFailures để test qua; chọn màu khác.
  3. Build docs, xem Màu & tương phản ở cả hai chế độ; mở playground xem bảng, nút, menu.
  4. MR đính kèm ảnh chụp trước/sau ở cả hai chế độ.
  5. Changeset minor cho @tasco/theme, mô tả thay đổi nhìn thấy được để team sản phẩm biết giao diện sẽ đổi.

Giá trị dùng làm seed cho antdv (primary, success, warning, error, info, link) còn ảnh hưởng màu nền antdv tự suy ra (Alert, Tag, nút hover). Đổi các token này thì xem thêm component antdv trong playground, không chỉ C*.

Thêm token màu ​

ts
// 1. tokens.ts — thêm field có TSDoc vào ColorTokens (thiếu TSDoc là build docs fail)
export interface ColorTokens {
  // ...
  /** Nền nhãn "Nháp" — xám ấm, tách khỏi surface-muted. */
  draftSoft: string
}

// 2. tokens.ts — giá trị cho CẢ HAI chế độ (TypeScript báo lỗi nếu thiếu)
export const lightTokens: TascoTokens = { color: { /* ... */ draftSoft: '#f4f1ec' } /* ... */ }
export const darkTokens: TascoTokens = { color: { /* ... */ draftSoft: '#26221c' } /* ... */ }

// 3. css-vars.ts — tên biến theo kebab-case của field
'--tasco-color-draft-soft': c.draftSoft,
  1. antdv cần đọc token này (hiếm) thì map thêm trong toAntdToken của antd-theme.ts.
  2. Token dùng làm chữ hoặc nền có chữ: thêm cặp vào contrastPairs trong contrast-pairs.ts, ghi usedBy là component sẽ dùng. Test khoá tương phản cho cả hai chế độ.
  3. Changeset minor cho @tasco/theme (thêm biến mới không phá app đang chạy).

Bảng token trong docs và dữ liệu list_tokens của @tasco/mcp tự có token mới sau khi build — không phải sửa tay.

Đổi tên hoặc xoá token ​

Biến --tasco-* là API công khai: CSS của app sản phẩm dùng trực tiếp. Đổi tên hay xoá là breaking — cần RFC, changeset major và mục trong Migration. Trong lúc chuyển đổi, giữ tên cũ trỏ cùng giá trị một bản major rồi mới xoá.

Mật độ ​

Muốn đổiSửa
Chiều cao ô nhập, nútdensity.controlHeight* — antdv nhận qua token toàn cục
Padding card, form, bảng, modaldensity.* rồi selector tương ứng trong base.css đọc biến --tasco-*
Mật độ của component antdv chưa có trong base.cssThêm rule vào base.css, bám biến --tasco-*, thêm field density nếu cần chỉnh được

antdv 4.2.6 bỏ qua theme.components trong ConfigProvider — đừng thử cấu hình padding theo component qua đó. Rule trong base.css cần !important vì style cssinjs của antdv có độ ưu tiên cao; mỗi khối rule có comment giải thích vì sao.

Font ​

Ba chỗ phải khớp nhau:

  1. fontStack / fontHeadingStack trong tokens.ts.
  2. Khai báo tĩnh --tasco-font-family* ở đầu base.css — để @nuxt/fonts quét thấy tên font lúc build.
  3. fonts.families trong nuxt.config.ts của layer: tên, độ đậm, subsets: ['vietnamese', 'latin'].

Font mới phải có bộ ký tự tiếng Việt đầy đủ. Thử với chuỗi có dấu chồng: "Người dùng đã huỷ yêu cầu xoá hoá đơn".

Chế độ tối ​

  • primary ở chế độ tối là màu chữ (sáng). Chỗ nào đặt chữ trắng lên nền primary thì chế độ tối dùng primary-active — quy tắc này đang nằm trong base.css với selector :root[data-theme='dark'].
  • *-text ở chế độ tối có thể trùng màu gốc nếu màu gốc đã đủ sáng.
  • Thêm màu nền mới thì kiểm tra cả chữ antdv tự vẽ lên nó (antdv trộn màu seed với nền tối, dễ tụt tương phản).

Checklist MR ​

  • [ ] Giá trị cho cả hai chế độ; TSDoc cho field mới.
  • [ ] pnpm --filter @tasco/theme test qua, không thêm knownFailures mới.
  • [ ] Cặp chữ/nền mới đã vào contrastPairs.
  • [ ] Ảnh chụp trước/sau, cả sáng và tối.
  • [ ] Changeset đúng mức: thêm → minor, đổi giá trị → minor, đổi tên/xoá → major kèm RFC và Migration.

Liên quan ​