Component & module reference cho FamilyEra (Lịch Việt) — bản tĩnh, đọc trực tiếp trên trình duyệt.
Nguồn: docs/design/Lich_Viet_Design_System.html (design canvas) đối chiếu với packages/ui/src (implementation đã ship) và packages/themes/src/tokens.ts (design tokens).
Nguồn duy nhất: packages/themes/src/tokens.ts. Ứng dụng chạy trên nền giấy ấm (canvas/surface) thay vì trắng/xám lạnh — tất cả các màu ngữ nghĩa (primary/accent/festive/sync) đều có cặp solid + tint để dùng cho nền đậm và nền nhạt.
darkTheme.colors). Trang này ưu tiên trình bày light‑mode; các ô dưới đây chỉ để đối chiếu giá trị — không có công tắc chuyển theme sống trên trang.Thang chữ cố định trong packages/themes/src/tokens.ts :: typography. Không có scale rời rạc theo breakpoint — 7 vai trò dưới đây dùng xuyên suốt app.
packages/ui/src/components/*), không phải token typography chung.
packages/ui/src/components/ · Single-concern, không orchestrate nhiều phần khác
4 variant × trạng thái default/loading/disabled. File: packages/ui/src/components/button/index.tsx. Prop color (primary/accent/festive/sync) đổi màu solid/tint bên dưới variant primary/ghost/destructive.
packages/ui/src/components/button giờ có prop size (lg 48px / md 38px, khớp ._LV Button.dc.html). Màu chữ primary khi disabled cũng đã đổi sang ink3 (#68746F) khớp đúng canvas — token riêng primaryDisabledInk đã được gỡ bỏ khỏi packages/themes vì không còn nơi nào dùng.
4 variant × 4 size. File: packages/ui/src/components/button-icon/index.tsx. Bán kính bo góc tăng dần theo size (11/13/16/19), variant solid có bóng đổ màu theo color.
._LV Icon Button.dc.html đặt tên biến thể khác (plain/tinted/destructive/solid/accent/ghost, size 26–54) — code đã ship gộp lại thành 4 variant (secondary/tint/solid/destructive) × 4 size chuẩn hoá (sm/md/lg/fab = 32/38/44/54px). Biến thể ghost (nền xám #F4F3EE) và size 26px của canvas chưa có trong component đã ship.
Bộ lọc / lựa chọn nhanh (quick-pick trong Date & Time Picker, bộ lọc màn Sự kiện). File: packages/ui/src/components/chip/index.tsx. 2 appearance (tint/solid) × active/inactive/disabled, có thể kèm count.
Nhãn phân loại nhỏ, không tương tác — gắn trên Event Row. File: packages/ui/src/components/tag/index.tsx. 5 tone theo ngữ nghĩa lịch (không phải theo màu tự do như bản canvas).
TagTone trong packages/ui/src/components/tag đã đổi tên tone khớp 1-1 với ._LV Tag.dc.html (jade/coral/red/blue/neutral — trước đây đặt theo ngữ nghĩa nội dung work/family/festive/personal/lunar) để dễ tái dùng cho dự án khác ngoài lịch Việt.
Công tắc bật/tắt (nhắc lịch, đồng bộ Google Calendar…). File: packages/ui/src/components/toggle/index.tsx. 46×28px, knob 22px, animate 200ms.
Chữ cái đầu tên, dùng trong Person & List Row. File: packages/ui/src/components/avatar/index.tsx. 5 size (34/38/42/44/46, bán kính tăng theo bậc thang) × 4 màu × trạng thái selected/memorial.
Ô ngày trong lưới lịch tháng — trái tim của Lịch Việt. File: packages/ui/src/components/day-cell/index.tsx. Cao 47px; viên thuốc (pill) 38×38 nổi phía sau số khi selected (đặc, có bóng) hoặc today (nhạt, không bóng); trọng số chữ leo thang theo mức độ quan trọng: medium → semibold (Chủ Nhật/hôm nay) → bold (ngày lễ/được chọn).
dots.slice(0,2)): festive (đỏ), accent (cam), primary (jade), muted (xám) — khi ô đang selected, chấm chuyển sang trắng 85%/50% để nổi trên nền đặc.
Khung nhập liệu dùng chung cho text field, ô kích hoạt (trigger) của Select/Date/TimePicker. Files: packages/ui/src/components/field/{field,text,trigger}.tsx. Nhãn viết hoa 10.5px phía trên; khung bo góc 14px, quầng sáng jade nhạt khi focus.
FieldText có prop secure (bật secureTextEntry) nhưng không có nút mắt (eye‑toggle) hiển thị/ẩn — ẩn ký tự đơn thuần, không có biến thể hình ảnh riêng để trình bày ở đây.
Ô kích hoạt mở bottom sheet chọn giá trị (dùng chung khung Field qua FieldTrigger, trailing luôn là chevron). File: packages/ui/src/components/select/index.tsx. Danh sách chọn hiển thị trong BottomSheet, mục đang chọn có dấu check màu primary.
Trong packages/ui component này tên là Tabs (packages/ui/src/components/tabs/index.tsx) — bản canvas gọi là "LV Segmented". Track nền track bo 13px, viên chọn nổi (pill) trắng có bóng nhẹ, trượt bằng animation theo layout đo được.
Chọn giờ kiểu bánh xe (wheel) 24h : phút theo bước 5/15 phút. File: packages/ui/src/components/timepicker/* (dùng chung WheelColumns/TimeWheel với Date Picker). Mở trong BottomSheet qua FieldTrigger.
._LV Time Picker.dc.html — packages/ui/src/components/timepicker hiện chỉ có bánh xe giờ:phút kiểu Tây, chưa implement can-chi. Khối lưới trên được dựng lại từ logic renderVals() của canvas (mốc ngày Quý Hợi), không phải từ code đã ship.
Chọn ngày Dương/Âm lịch qua lưới tháng (MonthGrid tái dùng DayCell). File: packages/ui/src/components/datepicker/*. Có 3 view nội bộ: ngày (day), chọn nhanh tháng/năm (monthYear, dạng wheel), giờ (time, nếu withTime).
monthYear, dùng lại WheelColumns):
packages/ui/src/modules/ · Ghép nhiều component lại thành một khối có ý nghĩa nghiệp vụ
Dòng sự kiện trong danh sách "Hôm nay" / màn Sự kiện. File: packages/ui/src/modules/event-row/index.tsx. Thanh màu 3.5px bên trái lấy theo color (primary/accent/festive/sync); có thể kèm Tag.
Hai biến thể trong nguồn: ListRow (module, có Avatar — dùng cho danh sách thành viên/gia phả) và List Row dạng dòng cài đặt phẳng (từ ._LV List Row.dc.html, dùng cho màn Cài đặt).
packages/ui/src/modules/list-row/index.tsx._LV List Row.dc.htmlswatch) hoặc giá trị bên phải; đường viền trên phân cách các dòng, dòng đầu tiên không có viềnSettingRow (packages/ui/src/modules/setting-row/index.tsx), export cùng ListRow từ @familyera/ui/modules.Thẻ thành viên gia phả, xếp ngang theo nhánh họ. File: packages/ui/src/modules/person/index.tsx. 88px rộng, 3 nhánh màu (paternal=jade, maternal=cam, inlaw=xanh dương) × trạng thái selected/memorial.
Avatar giờ có thêm tone neutral (nền track/chữ ink2), và Person nhận thêm prop color để ghi đè màu suy ra từ branch — khớp cách ._LV Person.dc.html cho chọn tự do 4 tone (jade/coral/blue/neutral) qua prop.
Sơ đồ cây gia phả (màn tree) vẽ tay bằng ba khối nguyên thuỷ — node (thẻ LV Person, xem Section L), line (thanh nối 1.5px kiểu "elbow": drop xuống → spine ngang → rise lên) và nhãn đời ở mép trái. Đây là phần quan trọng nhất của báo cáo này: chưa từng có component tái sử dụng nào cho sơ đồ cây trong packages/ui/src — chỉ có một icon tên "tree" (dùng cho tab bar "Gia phả"), không có primitive nào cho node/line/canvas. Nguồn: ._Lich Viet App.dc.html, khối st.screen === 'tree'.
renderVals(): hằng số hình học NODE_W=88, NODE_H=107, GAP=50 (⇒ ROW = NODE_H+GAP = 157), GEN_Y = [0, 157, 314, 471], HUB(g) = GEN_Y[g] + NODE_H + GAP/2, canvas rộng cố định 640px, cao CANVAS_H = GEN_Y[3] + NODE_H + 4 = 582px. Cuộn ngang khi màn hẹp hơn 640px (giống cách lv-wheel-col/App Mockup đã dùng ở Section P/R).gone:true → nhánh .lv-person.memorial + .lv-avatar-memorial (đã ship, Section H/L); người còn sống dùng tông theo nhánh — mặc định jade/primary (nội), aBg/aFg = #FDEEE8/#AB5434 khớp chính xác --accent-tint/--accent-ink (tái dùng .lv-avatar-accent), #EEF2FC/#4C67B0 khớp --sync-tint/--sync-ink (.lv-avatar-sync, dâu/rể). Nút "Minh Anh" (is-me:true) tô lại bằng .lv-person.selected + .lv-avatar-selected.lv-avatar-primary — đúng biến thể "selected" đã có sẵn ở Section L, không cần class riêng cho "current user".
drop(g,cx) / spine(g,x1,x2) / rise(g,cx) trong renderVals() — không phải đường chéo, luôn là elbow 90°.drop từ giữa cặp xuống hub · 1 spine ngang qua các con · mỗi con có 1 rise riêng.spine — chỉ một đường dọc duy nhất thẳng xuống con.#DDE3E0 của đường nối là giá trị hard-code riêng trong khối tree của canvas — không trùng token nào trong packages/themes/src/tokens.ts (gần nhất là --memorial-line #B9C6C1, nhưng nhạt hơn hẳn).apps/mobile/src/features/* · Ghép Components + Modules ở trên thành màn hình thật — không phải khối build riêng
Dựng lại minh hoạ (không pixel‑perfect) từ ._Lich Viet App.dc.html, ghép từ các component ở trên: header tháng + nút "Hôm nay", Segmented Tháng/Tuần, thẻ hero hôm nay (Dương + Âm lịch + giờ hoàng đạo + tiết khí), lưới ngày, danh sách sự kiện hôm nay, thanh điều hướng dưới cùng 5 mục + FAB thêm sự kiện.
._Lich Viet App.dc.html (2364 dòng, ~36 màn/state trong 5 nhóm: calendar/events/explore/tree/settings). Trang này chỉ dựng lại màn Lịch (home) làm đại diện cho nhóm calendar — toàn bộ ~30 màn còn lại (sự kiện, gia phả, khám phá, cài đặt, các trạng thái lịch khác) được trình bày đầy đủ ở Section S–W bên dưới.
7 màn còn lại trong nhóm tree (st.screen): chi tiết thành viên, danh sách giỗ, tra cứu xưng hô, mời/chia sẻ cây, trạng thái rỗng + onboarding, và form thêm người. Toàn bộ nội dung mẫu (tên, ngày, vai vế) lấy nguyên văn từ renderVals() trong ._Lich Viet App.dc.html.
goPerson). Header dùng avatar lớn 70px + 2 LV Tag; bên dưới là 3 khối: thông tin (personRows), quan hệ (relations, tái dùng .lv-list-row), và ghi nhớ tự do.goneHint/toggleGone) không nằm ở màn chi tiết này trong nguồn — nó thuộc form Thêm người (xem card cuối cùng bên dưới). Tag "Ông nội" (tone="jade") và "Đời thứ 5" (tone="neutral") tái dùng đúng .lv-tag-work/.lv-tag-lunar đã ship — giá trị màu trùng khớp 1-1.gioGroups), mỗi dòng có avatar memorial + tên/vai vế/ngày âm lịch + cột phải hiện ngày dương quy đổi và số ngày còn lại; dòng gần nhất tô màu jade để nổi bật.items chỉ liệt kê 2 người — giữ nguyên như trong renderVals(), có thể canvas gốc chủ ý bớt 1 dòng để minh hoạ hoặc đây là chỗ dữ liệu mẫu chưa khớp; không tự ý thêm người thứ 3.relPath = đường quan hệ từng bước, quickRel = tra nhanh gợi ý sẵn).members (đang cùng giữ cây, có vai trò Quản lý/Biên tập/Chỉ xem) và pending (yêu cầu chờ duyệt, mỗi thẻ có nút Duyệt/Từ chối riêng).onboardPeople), có thể bỏ trống và thêm sau.relRoles, mặc định "Con" đang chọn), rồi đúng vị trí chứa nút "Đã mất" (goneHint/toggleGone) + trường "Ngày giỗ" chỉ bật khi đã mất — mặc định canvas khởi tạo personGone: true nên cả hai đều hiện sẵn.LV Select accent="true" ("Quan hệ với", "Ngày giỗ") tô chữ giá trị màu --primary — suy luận trực quan từ canvas, prop này chưa thấy trong packages/ui/src/components/select đã ship (giống các ghi chú "design canvas vs. shipped" ở Section C/D/F/L/P).Tab thứ 3 của thanh điều hướng dưới. Gồm trang chủ Khám phá (menu) và 6 màn con: đếm ngược & lịch trình Tết, ngày tốt xấu theo mục đích, 12 con giáp & tuổi, hướng xuất hành, lễ truyền thống, 24 tiết khí. Nguồn: ._Lich Viet App.dc.html (isExplore/isTet/isGoodDays/isZodiac/isDirection/isHoliday/isTerms) — chưa có màn hình React Native tương ứng, toàn bộ nội dung dưới đây là canvas-only, ghép từ các component đã có ở phần trên (Chip, Avatar, List Row, Tag…) chưa có trong code.
Tile), danh sách lễ/tiết khí sắp tớipackages/ui/src/modules/tile (icon tròn + title + subtitle, 4 tông màu primary/accent/festive/sync); danh sách "Sắp tới" tái dùng nguyên ListRow + Avatar (đã có ở Section H/K). Khối "Giờ hoàng đạo" và card đếm ngược Tết chưa có component riêng.purposes) để lọc danh sách goodDays — mỗi ngày có điểm phù hợp 1–3 vạchscore.slice(0,3), vạch on tô jade, còn lại tô border..phone-hero (Section R) — cùng một hoạ tiết vòng tròn đồng tâmpackages/ui/src.TERMS — từ Lập Xuân 04/02 đến Đại Hàn 20/01); trên đây rút gọn 7 dòng quanh mốc hiện tại cho gọn trang. Tông màu: đã qua → chữ/chấm mờ placeholder; hiện tại → nền primaryTint, chữ/chấm primary; sắp tới → ink mặc định.Tab Cài đặt cùng các màn con (đồng bộ lịch, thông báo, quyền hệ thống, widget, chế độ tối) và các lớp phủ phản hồi tạm thời (toast/banner/push) xuất hiện đè lên bất kỳ màn nào. Nguồn: ._Lich Viet App.dc.html (isSettings/isSync/isNotifs/isPermissions/isWidgets/isDark/showToast/showBanner/isPush).
LV List Row/Setting Row + Toggle từ Section K).phone-hero) + danh sách nhóm theo thời gian, dòng chưa đọc nền trắng viền jade nhạtpackages/ui — toàn bộ khối trên chỉ minh hoạ ý tưởng từ canvas..lv-month-card/.lv-day/.lv-event-row qua ghi đè biến CSS cục bộ.lv-x-dark-preview (--canvas #0F1917 · --surface #16231F · --primary #17A184… — trùng bảng "Dark theme tham khảo" ở Section A), không định nghĩa lại toàn bộ component ở chế độ tối.packages/ui/src/modules/toastpackages/ui/src/modules/toast (tone success/error, dùng token toastSuccess/toastSuccessTint). chưa có trong code Banner (dynamic-island) và Push notification (lock screen) chưa có component/module tương ứng — đây là overlay hệ điều hành, nằm ngoài phạm vi UI kit RN thông thường.Các màn liên quan lịch/sự kiện chưa xuất hiện ở Section R (chỉ dựng màn Lịch tháng): tuần, chọn nhanh tháng/năm dạng lưới thẻ, chi tiết sự kiện, đổi lịch Âm↔Dương, trạng thái rỗng, tìm kiếm, thêm sự kiện. Nguồn: ._Lich Viet App.dc.html (isWeek/isMonthPicker/isEventDetail/isConverter/isEmptyEvents/isEmptySearch/isSearch/isAdd).
packages/ui/src/modules/event-blocktop/height tính sẵn trong renderVals() — về hình dạng (thanh màu trái + tiêu đề + giờ, nền/chữ theo color) khớp hệt EventBlock đã ship, khác biệt duy nhất là EventBlock chưa expose layout lưới-giờ dùng chung với nhãn giờ bên trái..lv-echo-card (2 cột) đã có ở Section P/Q; danh sách thuộc tính khớp module packages/ui/src/modules/info-list.lv-icon-btn-lg.lv-icon-btn-solid; danh sách xem nhanh tái dùng .lv-x-kv-row ở trênlv-chip)