Nemo12 Docs

Appearance

DS-001 — Nemo12 Design System ​

Một Design System duy nhất cho toàn ecosystem. Bài học legacy: chuyenchon + sutucon có tổng cộng 6+ hệ token song song (--ds-* copy-sync 2 bản, shadcn @theme lệch nhau per app, --ui-* bridge, ~25k dòng CSS tay per-page) và mỗi app một bản fork button.tsx. Nemo12 cấm lặp lại điều đó.

1. Kiến trúc package (REQ-PLT-06) ​

text
packages/design-system/
├── tokens/            # CSS custom properties — nguồn sự thật duy nhất
│   ├── base.css       # màu, spacing, radius, elevation, motion, typography scale
│   └── themes/        # theme-turtle … theme-whale, theme-marlins (lớp mỏng: accent + illustration)
├── tailwind/          # @theme mapping cho Tailwind v4 (CSS-first, KHÔNG tailwind.config.js)
├── components/        # shadcn (React 19 + Radix) — Nemo12 sở hữu source
├── patterns/          # layout shell, page templates, empty/error/loading states
├── icons/  typography/  index.css
  • Phân phối = npm workspace package (@nemo12/design-system). Cấm copy-sync file (bỏ cơ chế sync-ds.mjs của legacy — RISK-012).
  • Tailwind v4 mới nhất (CSS-first @theme); shadcn CLI mới nhất, base Radix (chuẩn cộng đồng, dài hạn — không theo nhánh Base UI của simba).
  • School theme chỉ được đổi lớp mỏng: --accent, hình minh họa, tông; không fork component.

2. Tokens (trích chuẩn khởi điểm) ​

css
:root {
  /* brand */
  --n12-ocean-900: #0B2D48; --n12-ocean-700: #14507E; --n12-ocean-500: #1F7AB8;
  --n12-coral-500: #FF6B4A; --n12-sun-400: #FFB347; --n12-seafoam-200: #DFF3EC;
  --n12-sand-50: #FAF6F0; --n12-ink-900: #17222B;
  /* semantic */
  --background; --foreground; --card; --primary; --secondary; --muted;
  --destructive; --success; --warning; --border; --ring; --radius: 0.75rem;
}
.theme-turtle  { --accent: #2E9E6B }  .theme-shark { --accent: #E4572E }
.theme-octopus { --accent: #7C5CBF }  .theme-squid { --accent: #1F7AB8 }
.theme-ray     { --accent: #C99700 }  .theme-whale { --accent: #145DA0 }

(Palette đại dương — đề xuất v0.1, chờ chủ dự án duyệt: Q-056. Semantic tokens theo hợp đồng shadcn để components dùng nguyên bản.)

3. Typography & accessibility constraints — kế thừa CÓ CHỦ ĐÍCH ​

Legacy quy định Arial toàn hệ + sàn 14px như một ràng buộc sản phẩm (niềm tin phụ huynh, dễ đọc cho học sinh). Nemo12 giữ tinh thần, nới thực thi:

  • Font: system font stack (-apple-system, Segoe UI, Roboto, Arial, sans-serif) — nhanh, không tải webfont cho body text; display font tùy chọn cho marketing.
  • Sàn 14px cho mọi text; line-height ≥1.5 body; kiểm bằng lint QG-007 (không dùng !important toàn cục kiểu legacy).
  • WCAG 2.1 AA: contrast ≥4.5:1, focus ring luôn hiển thị, prefers-reduced-motion tôn trọng, touch target ≥44px (mobile-ready — Q-029).

4. Components ​

Base từ shadcn (Button, Input, Card, Dialog, Tabs, Table, Toast, Form…) + Nemo12 patterns: MasteryBar (mastery+confidence hai lớp — REQ-VIS-04), NodeStateBadge (8 trạng thái), GoalReadiness, TrajectorySpark, WorkloadMeter, EvidenceCard, CommentThread (SDD-005), MediaUploader (SDD-009). Mọi component có story/example trong apps/docs.

5. Quy tắc sử dụng (QG-007 enforce) ​

  1. App không define màu/spacing/radius mới — chỉ dùng tokens.
  2. Không fork component; thiếu thì thêm vào package qua PR.
  3. Không CSS file per-page kiểu legacy; Tailwind utilities + component styles.
  4. Dark mode: chưa bật phase 1 (tự quyết Q-058) nhưng tokens semantic sẵn sàng để bật sau.
  5. Registry: có thể phát hành private shadcn registry cho Nemo12 (SRC-002 §5) — phase sau.

Trace ​

REQ-PLT-06 → toàn bộ. QG-007 định nghĩa compliance checks.