@sd-angular/core 19.0.0-beta.103 → 19.0.0-beta.105

package/assets/scss/README.md

@@ -1,29 +1,33 @@
-# SD Angular — SCSS Documentation
+# `@sd-angular/core` — Assets & SCSS Reference
+
+> **Mục đích tài liệu này (cho người + AI agent):** liệt kê chính xác mọi utility class, design token, font, image, theme mixin mà `@sd-angular/core` ship trong `assets/`. AI agent chỉ được sinh template dùng class **nằm trong danh sách dưới đây** — nếu cần class mới, phải tạo trong `core/utilities/*.scss` trước.
+
+---
 
 ## Mục lục
 
 1. [Cài đặt vào Angular](#1-cài-đặt-vào-angular)
-2. [Hệ thống màu sắc](#2-hệ-thống-màu-sắc)
-3. [Custom theme](#3-custom-theme)
-4. [Utility classes](#4-utility-classes)
-   - [Spacing](#spacing--margin--padding)
-   - [Sizing](#sizing--width--height)
-   - [Border](#border)
-   - [Grid & Layout](#grid--layout)
-   - [Flexbox](#flexbox)
-   - [Display](#display)
-   - [Gap](#gap)
-   - [Typography](#typography)
-   - [Overflow](#overflow)
-   - [Position](#position)
-   - [Elevation](#elevation)
-   - [Misc](#misc)
+2. [Cấu trúc thư mục `assets/`](#2-cấu-trúc-thư-mục-assets)
+3. [Hệ thống màu sắc](#3-hệ-thống-màu-sắc) — `--sd-*` tokens + `.text-*` / `.bg-*` / `.border-*`
+4. [Typography tokens](#4-typography-tokens) — `T{size}{weight}` + `fs-*` + `font-weight-*`
+5. [Layout & Grid](#5-layout--grid) — `row` / `col-*` / `grid-container` / `grid-cols-*`
+6. [Flexbox utilities](#6-flexbox-utilities) — `d-flex` + `flex-*` + `align-*` + `justify-*`
+7. [Spacing](#7-spacing) — `m-*` / `p-*` / `gap-*`
+8. [Sizing](#8-sizing) — `w-*` / `h-*` / `min-*` / `max-*`
+9. [Border & radius](#9-border--radius) — `border` / `border-{side}` / `rounded-*`
+10. [Display, position, overflow, visibility](#10-display-position-overflow-visibility)
+11. [Cursor, vertical-align, misc](#11-cursor-vertical-align-misc)
+12. [Elevation (mat-elevation-z0–z8)](#12-elevation-mat-elevation-z0z8)
+13. [Reset / Reboot baseline](#13-reset--reboot-baseline)
+14. [Custom theme](#14-custom-theme)
+15. [Fonts & Images shipped](#15-fonts--images-shipped)
+16. [What is NOT shipped](#16-what-is-not-shipped) — anti-confusion cho AI
 
 ---
 
 ## 1. Cài đặt vào Angular
 
-Thêm vào `angular.json` (trong phần `styles` của build target):
+`angular.json`:
 
 ```json
 "styles": [
@@ -32,45 +36,114 @@ Thêm vào `angular.json` (trong phần `styles` của build target):
 ]
 ```
 
-`sd-core.scss` bao gồm toàn bộ: reset CSS, utilities, màu theme, form overrides, scrollbar, và Angular Material theme.
+`sd-core.scss` là entry point duy nhất — auto-load reset, utilities, color theme, form overrides, scrollbar, Angular Material theme. Không cần import partial nào riêng lẻ.
+
+> Convention chung: **mọi utility class đều có `!important`** để đảm bảo override được Angular Material (thường có specificity cao).
 
 ---
 
-## 2. Hệ thống màu sắc
+## 2. Cấu trúc thư mục `assets/`
+
+```
+projects/sd-angular/assets/
+├── fonts/
+│   ├── fonts.scss                     # @font-face khai báo cho Roboto + Material Icons + Material Symbols
+│   ├── material-icons/                # 2 file .woff2 (icons-v145 + outlined-v110)
+│   ├── material-symbols/              # 1 file .woff2 (symbols-v29)
+│   └── roboto/                        # 4 file .woff2 (regular, italic, 500, 600 — latin + vietnamese)
+├── images/                            # SVG illustrations (18 file — empty-state, error, success...)
+│   ├── coming-soon.svg                # Trang chưa sẵn sàng
+│   ├── data-empty.svg                 # Empty state cho table/list
+│   ├── expired.svg                    # Session expired
+│   ├── file-error.svg                 # Upload file lỗi
+│   ├── filter-empty.svg               # Không match filter
+│   ├── filter-required.svg            # Yêu cầu bộ lọc trước khi load
+│   ├── forbidden.svg                  # 403
+│   ├── image-error.svg                # Image load fail
+│   ├── maintenance.svg                # Trang đang bảo trì
+│   ├── not-found.svg                  # 404
+│   ├── offline.svg                    # Mất mạng
+│   ├── submitted.svg                  # Gửi form thành công
+│   ├── success.svg                    # Generic success
+│   ├── unauthorized.svg               # 401
+│   └── unknown-error.svg              # 500 / fallback
+└── scss/
+    ├── sd-core.scss                   # ENTRY (chỉ file này được import từ host app)
+    ├── ckeditor5.scss                 # Override style cho CKEditor 5 (opt-in)
+    ├── core/
+    │   ├── color.scss                 # Color map + CSS var declarations
+    │   ├── form.scss                  # Override Angular Material form (input/select/checkbox/radio)
+    │   ├── image.scss                 # Tiện ích background-image cho 18 illustration SVG ở trên
+    │   ├── scrollbar.scss             # Custom scrollbar (webkit + firefox)
+    │   └── utilities/
+    │       ├── _index.scss            # Forward toàn bộ partial bên dưới
+    │       ├── _base.scss             # Reset/reboot baseline (box-sizing, body, headings, forms…)
+    │       ├── _border.scss           # rounded-* + border + border-{side}
+    │       ├── _display.scss          # d-none/block/inline/inline-block/flex/inline-flex/grid
+    │       ├── _elevation.scss        # mat-elevation-z0–z8
+    │       ├── _flexbox.scss          # flex-1/none/auto, direction, wrap, grow/shrink, align/justify
+    │       ├── _gap.scss              # gap-* / gap-x-* / gap-y-*
+    │       ├── _grid.scss             # row/col 12-column + .grid-container + col-span-*
+    │       ├── _misc.scss             # align-{middle…}, cursor-*, visible/invisible
+    │       ├── _overflow.scss         # overflow-*
+    │       ├── _position.scss         # position-relative/absolute/fixed/sticky/static
+    │       ├── _sizing.scss           # w-* / h-* + min/max + w-full/screen/auto/fit
+    │       ├── _spacing.scss          # m-*, p-* (mt/mr/mb/ml/mx/my, pt/pr/pb/pl/px/py) + m-auto
+    │       └── _typography.scss       # T{n}{M|R} tokens + fs-* + font-weight-* + text-*
+    └── themes/
+        ├── default.scss               # sd.theme() mixin — override `--sd-*` color tokens
+        └── material-theme.scss        # Angular Material M2 theme baseline
+```
 
-Màu được định nghĩa dưới dạng **CSS custom properties** có tiền tố `--sd-*`, cho phép override runtime (không cần recompile SCSS).
+---
 
-### Màu mặc định
+## 3. Hệ thống màu sắc
 
-| Token | CSS Variable | Giá trị mặc định | Dùng cho |
+Màu được định nghĩa dưới dạng **CSS custom properties** với prefix `--sd-*`, cho phép override runtime (không cần recompile SCSS).
+
+### 3.1 Color tokens
+
+| Token              | CSS variable           | Default     | Dùng cho |
 |---|---|---|---|
-| `primary` | `--sd-primary` | `#2A66F4` | Màu chủ đạo — button, checkbox, accent |
-| `primary-light` | `--sd-primary-light` | `#EAF1FF` | Background nhẹ của primary |
-| `primary-dark` | `--sd-primary-dark` | `#1C4AD9` | Hover/active state của primary |
-| `info` | `--sd-info` | `#2962FF` | Link, thông tin, badge info |
-| `info-light` | `--sd-info-light` | `#E7E9FF` | Background nhẹ của info |
-| `info-dark` | `--sd-info-dark` | `#2240CC` | Hover state của info |
-| `success` | `--sd-success` | `#4CAF50` | Trạng thái thành công, validation OK |
-| `success-light` | `--sd-success-light` | `#DBEFDC` | Background nhẹ của success |
-| `success-dark` | `--sd-success-dark` | `#39833C` | Hover state của success |
-| `warning` | `--sd-warning` | `#FF9600` | Cảnh báo, trạng thái cần chú ý |
-| `warning-light` | `--sd-warning-light` | `#FFEACC` | Background nhẹ của warning |
-| `warning-dark` | `--sd-warning-dark` | `#BF7000` | Hover state của warning |
-| `error` | `--sd-error` | `#F82C13` | Lỗi, validation fail, trạng thái nguy hiểm |
-| `error-light` | `--sd-error-light` | `#FED5D0` | Background nhẹ của error |
-| `error-dark` | `--sd-error-dark` | `#BA200E` | Hover state của error |
-| `secondary` | `--sd-secondary` | `#212121` | Text phụ, icon secondary |
-| `secondary-light` | `--sd-secondary-light` | `#E9E9E9` | Background nhẹ |
-| `secondary-dark` | `--sd-secondary-dark` | `#000000` | — |
-| `light` | `--sd-light` | `#F8F9FA` | Background trang, surface nhẹ |
-| `dark` | `--sd-dark` | `#343A40` | Text đậm, dark surface |
-| `black500` | `--sd-black500` | `#212121` | Text chính |
-| `black400` | `--sd-black400` | `#757575` | Text phụ, placeholder |
-| `black300` | `--sd-black300` | `#BFBFBF` | Divider, border nhẹ |
-| `black200` | `--sd-black200` | `#E6E6E6` | Border mặc định, separator |
-| `black100` | `--sd-black100` | `#F2F2F2` | Background disabled, row hover |
-
-### Dùng màu trong SCSS component
+| `primary`          | `--sd-primary`         | `#2A66F4`   | Màu chủ đạo — button, checkbox, accent |
+| `primary-light`    | `--sd-primary-light`   | `#EAF1FF`   | Background nhẹ của primary |
+| `primary-dark`     | `--sd-primary-dark`    | `#1C4AD9`   | Hover/active state của primary |
+| `info`             | `--sd-info`            | `#2962FF`   | Link, thông tin, badge info |
+| `info-light`       | `--sd-info-light`      | `#E7E9FF`   | Background nhẹ của info |
+| `info-dark`        | `--sd-info-dark`       | `#2240CC`   | Hover state của info |
+| `success`          | `--sd-success`         | `#4CAF50`   | Trạng thái thành công, validation OK |
+| `success-light`    | `--sd-success-light`   | `#DBEFDC`   | Background nhẹ của success |
+| `success-dark`     | `--sd-success-dark`    | `#39833C`   | Hover state của success |
+| `warning`          | `--sd-warning`         | `#FF9600`   | Cảnh báo, trạng thái cần chú ý |
+| `warning-light`    | `--sd-warning-light`   | `#FFEACC`   | Background nhẹ của warning |
+| `warning-dark`     | `--sd-warning-dark`    | `#BF7000`   | Hover state của warning |
+| `error`            | `--sd-error`           | `#F82C13`   | Lỗi, validation fail, trạng thái nguy hiểm |
+| `error-light`      | `--sd-error-light`     | `#FED5D0`   | Background nhẹ của error |
+| `error-dark`       | `--sd-error-dark`      | `#BA200E`   | Hover state của error |
+| `secondary`        | `--sd-secondary`       | `#212121`   | Text phụ, icon secondary |
+| `secondary-light`  | `--sd-secondary-light` | `#E9E9E9`   | Background nhẹ |
+| `secondary-dark`   | `--sd-secondary-dark`  | `#000000`   | — |
+| `light`            | `--sd-light`           | `#F8F9FA`   | Background trang, surface nhẹ |
+| `dark`             | `--sd-dark`            | `#343A40`   | Text đậm, dark surface |
+| `black500`         | `--sd-black500`        | `#212121`   | Text chính |
+| `black400`         | `--sd-black400`        | `#757575`   | Text phụ, placeholder |
+| `black300`         | `--sd-black300`        | `#BFBFBF`   | Divider, border nhẹ |
+| `black200`         | `--sd-black200`        | `#E6E6E6`   | Border mặc định, separator |
+| `black100`         | `--sd-black100`        | `#F2F2F2`   | Background disabled, row hover |
+
+### 3.2 Color utility classes
+
+Mọi token ở §3.1 đều sinh 3 class:
+
+| Pattern         | Ví dụ                     |
+|---|---|
+| `.text-{token}` | `text-primary`, `text-error`, `text-black400` |
+| `.bg-{token}`   | `bg-primary-light`, `bg-error-light`, `bg-white` |
+| `.border-{token}` | `border-primary`, `border-black200` |
+
+`white` / `black` luôn có sẵn ngoài bảng trên: `.text-white` / `.text-black` / `.bg-white` / `.bg-black`.
+
+### 3.3 Dùng màu trong component SCSS
 
 ```scss
 @use '@sd-angular/core/assets/scss/core/color.scss' as color;
@@ -83,194 +156,74 @@ Màu được định nghĩa dưới dạng **CSS custom properties** có tiền
 }
 ```
 
-### Dùng màu qua utility class trong template
-
-```html
-<!-- Text color -->
-<span class="text-primary">Primary</span>
-<span class="text-error">Lỗi</span>
-<span class="text-secondary">Phụ</span>
-<span class="text-success">Thành công</span>
-<span class="text-warning">Cảnh báo</span>
-
-<!-- Background color -->
-<div class="bg-primary-light">...</div>
-<div class="bg-error-light">...</div>
-<div class="bg-white">...</div>
-
-<!-- Border color -->
-<div class="border-primary">...</div>
-```
-
-Tất cả token đều có class: `.text-{token}`, `.bg-{token}`, `.border-{token}`.
-
----
-
-## 3. Custom theme
-
-Trong `styles.scss` của ứng dụng, import theme mixin và Angular Material, sau đó gọi `sd.theme()` với các màu muốn override.
-
-Chỉ cần khai báo các màu muốn **thay đổi** — màu không khai báo sẽ dùng giá trị mặc định.
+Hoặc đọc trực tiếp CSS var (recommended cho runtime override):
 
 ```scss
-@use '@sd-angular/core/assets/scss/themes/default' as sd;
-@use '@angular/material' as mat;
-@include mat.core();
-
-html {
-  @include sd.theme(
-    (
-      primary:         #AE7129,
-      primary-light:   #F4F2F1,
-      primary-dark:    #6B4414,
-    )
-  );
+.my-element {
+  color: var(--sd-primary);
+  background: var(--sd-primary-light);
 }
-
-// --- Angular Material M2 Palette ---
-
-$custom-primary-palette: mat.m2-define-palette((
-  50: #F4F2F1,
-  100: #E7E1DA,
-  200: #DAC8B4,
-  300: #D1AC80,
-  400: #CD9450,
-  500: #AE7129,
-  600: #8D5A1E,
-  700: #6B4414,
-  800: #4B2F0E,
-  900: #34210A,
-  contrast: (
-    600: white,
-    700: white,
-    800: white,
-    900: white,
-  )
-));
-
-$custom-accent-palette: mat.m2-define-palette((
-  50: #F1F3F1,
-  100: #DCE5DD,
-  200: #BBD3BC,
-  300: #8FC291,
-  400: #67B76A,
-  500: #4CAF50,
-  600: #3A8C3D,
-  700: #29692C,
-  800: #1C471E,
-  900: #132F14,
-  contrast: (
-    700: white,
-    800: white,
-    900: white,
-  )
-));
-
-$custom-warn-palette: mat.m2-define-palette((
-  50: #F5F0F0,
-  100: #EAD9D6,
-  200: #E4B0AA,
-  300: #E6786B,
-  400: #EE4430,
-  500: #F82C13,
-  600: #D11801,
-  700: #9A1100,
-  800: #680B00,
-  900: #440700,
-  contrast: (
-    600: white,
-    700: white,
-    800: white,
-    900: white,
-  )
-));
-
-$custom-theme: mat.m2-define-light-theme((
-  color: (
-    primary: $custom-primary-palette,
-    accent:  $custom-accent-palette,
-    warn:    $custom-warn-palette,
-  ),
-  density: -3,
-));
-
-@include mat.all-component-themes($custom-theme);
 ```
 
-> **Lưu ý:** `sd.theme()` và `mat.all-component-themes()` đều cần được gọi trong `styles.scss`, không phải trong component SCSS.
-
 ---
 
-## 4. Utility classes
+## 4. Typography tokens
 
-Tất cả utility classes đều có `!important` để đảm bảo override được khi kết hợp với Angular Material.
+### 4.1 Design token classes — `T{size}{weight}`
 
----
+Quy ước: `M` = Medium (500), `R` = Regular (400). Mỗi class gồm `font-size` + `font-weight` + `line-height` chuẩn hóa.
 
-### Spacing — Margin & Padding
+| Class           | Font size     | Weight    | Line height |
+|---|---|---|---|
+| `T48M` / `T48R` | 48px          | 500 / 400 | 56px |
+| `T32M` / `T32R` | 32px          | 500 / 400 | 48px |
+| `T24M` / `T24R` | 24px / 20px*  | 500 / 400 | 28px |
+| `T20M` / `T20R` | 20px          | 500 / 400 | 28px |
+| `T18M` / `T18R` | 18px          | 500 / 400 | 28px |
+| `T16M` / `T16R` | 16px          | 500 / 400 | 24px |
+| `T14M` / `T14R` | 14px          | 500 / 400 | 20px |
+| `T12M` / `T12R`† | 12px          | 500 / 400 | 16px |
+| `T10M` / `T10R` | 10px          | 500 / 400 | 12px |
 
-Hệ thống spacing theo đơn vị **px**, range từ 0 đến 200.
+\* `T24R` font-size 20px (quirk lịch sử — `T24M` là 24px). Khi cần 24px/400, dùng `T20R` 20px hoặc cặp `fs-24 + font-weight-normal`.
+† `T12R` dùng `!important` vì hay bị Angular Material override.
 
-```
-m-{n}     mt-{n}    mr-{n}    mb-{n}    ml-{n}    mx-{n}    my-{n}
-p-{n}     pt-{n}    pr-{n}    pb-{n}    pl-{n}    px-{n}    py-{n}
-```
+### 4.2 Font-size utilities (px-based)
 
-Ví dụ: `m-0`, `mt-8`, `px-16`, `py-24`, `mb-4`
-
-**Auto margin:**
 ```
-m-auto   mt-auto   mr-auto   mb-auto   ml-auto   mx-auto   my-auto
+fs-0   fs-1 … fs-200
 ```
 
----
-
-### Sizing — Width & Height
+Dùng khi cần override nhanh, **không thay** design token. Output: `font-size: {n}px !important`.
 
-**Theo px** (0–200): `w-{n}`, `h-{n}`
+### 4.3 Font-weight
 
-**Theo %/keyword:**
-
-| Class | CSS |
+| Class                  | weight |
 |---|---|
-| `w-full` | `width: 100%` |
-| `w-100` | `width: 100%` (alias) |
-| `w-auto` | `width: auto` |
-| `w-screen` | `width: 100vw` |
-| `w-fit` | `width: fit-content` |
-| `h-full` | `height: 100%` |
-| `h-100` | `height: 100%` (alias) |
-| `h-auto` | `height: auto` |
-| `h-screen` | `height: 100vh` |
-| `h-fit` | `height: fit-content` |
-| `min-h-full` | `min-height: 100%` |
-| `min-h-screen` | `min-height: 100vh` |
-| `min-w-full` | `min-width: 100%` |
-| `max-h-full` | `max-height: 100%` |
-| `max-w-full` | `max-width: 100%` |
-
----
-
-### Border
+| `font-weight-light`    | 300 |
+| `font-weight-normal`   | 400 |
+| `font-weight-medium`   | 500 |
+| `font-weight-bold`     | 600 |
+| `font-weight-bolder`   | 700 |
 
-**Border-radius** (0–200px): `rounded-{n}`, `rounded-full` (9999px)
+### 4.4 Text alignment / wrap / transform
 
-**Border utilities:**
+```
+text-left   text-center   text-right   text-justify
+text-wrap   text-nowrap   text-ellipsis   text-break
+text-uppercase   text-lowercase   text-capitalize
+```
 
-| Class | CSS |
+| Class            | Output |
 |---|---|
-| `border` | `border: 1px solid var(--sd-black200)` |
-| `border-0` | `border: 0` |
-| `border-top` | `border-top: 1px solid var(--sd-black200)` |
-| `border-bottom` | `border-bottom: 1px solid var(--sd-black200)` |
-| `border-left` | `border-left: 1px solid var(--sd-black200)` |
-| `border-right` | `border-right: 1px solid var(--sd-black200)` |
+| `text-ellipsis`  | `white-space: nowrap; overflow: hidden; text-overflow: ellipsis` (yêu cầu container có width cố định) |
+| `text-break`     | `overflow-wrap: break-word; word-break: break-word` (xuống dòng giữa ký tự — URL, hash, mã dài) |
 
 ---
 
-### Grid & Layout
+## 5. Layout & Grid
 
-#### Flexbox row/col
+### 5.1 Flexbox row/col 12-column
 
 ```html
 <div class="row">
@@ -279,35 +232,36 @@ m-auto   mt-auto   mr-auto   mb-auto   ml-auto   mx-auto   my-auto
 </div>
 ```
 
-`.row` là flex container có gutter `16px`. Các class `.col-{1-12}` chia theo 12 cột.
+`.row` là flex container có gutter `16px` (margin âm trừ gutter + padding nửa gutter trên `> *`).
 
 **Gutter variants:**
 
-| Class | Gutter |
+| Class    | Gutter |
 |---|---|
-| `row` | 16px (mặc định) |
+| `row`    | 16px (mặc định) |
 | `row-md` | 8px |
 | `row-sm` | 4px |
 | `row-xs` | 2px |
 
-**Responsive columns** (mobile-first — áp dụng từ breakpoint trở lên):
+**Auto-width column:** `.col` (chiếm phần còn lại, `flex: 1 1 0%`).
+
+**Responsive columns** (mobile-first — class chỉ kích hoạt khi viewport ≥ breakpoint):
 
-| Class | Min-width |
+| Pattern         | Min-width |
 |---|---|
-| `col-sm-{1-12}` | ≥ 576px |
-| `col-md-{1-12}` | ≥ 768px |
-| `col-lg-{1-12}` | ≥ 992px |
-| `col-xl-{1-12}` | ≥ 1200px |
+| `col-sm-{1-12}` / `col-sm` | ≥ 576px |
+| `col-md-{1-12}` / `col-md` | ≥ 768px |
+| `col-lg-{1-12}` / `col-lg` | ≥ 992px |
+| `col-xl-{1-12}` / `col-xl` | ≥ 1200px |
 
-Ví dụ:
 ```html
 <div class="row">
-  <!-- Full width trên mobile, 50% từ md trở lên, 33% từ lg trở lên -->
+  <!-- 100% trên mobile, 50% từ md+, 33% từ lg+ -->
   <div class="col-md-6 col-lg-4">...</div>
 </div>
 ```
 
-#### CSS Grid container
+### 5.2 CSS Grid container
 
 ```html
 <div class="grid-container grid-cols-3">
@@ -317,208 +271,334 @@ Ví dụ:
 </div>
 ```
 
-| Class | Mô tả |
+| Class                | Mô tả |
 |---|---|
-| `grid-container` | `display: grid`, gutter cột 8px |
-| `grid-cols-{1-12}` | Số cột của grid |
-| `col-span-{1-12}` | Chiếm n cột |
-| `col-span-full` | Chiếm toàn bộ chiều ngang |
-| `row-span-{1-12}` | Chiếm n hàng |
-| `row-span-full` | Chiếm toàn bộ chiều dọc |
+| `grid-container`     | `display: grid`, `column-gap: 8px`, `row-gap: 0` |
+| `grid-cols-{1-12}`   | Số cột |
+| `col-span-{1-12}`    | Item chiếm n cột |
+| `col-span-full`      | Item chiếm toàn bộ chiều ngang |
+| `row-span-{1-12}`    | Item chiếm n hàng |
+| `row-span-full`      | Item chiếm toàn bộ chiều dọc |
 
----
+> Các class `col-span-*` / `row-span-*` chỉ có hiệu lực **bên trong** `.grid-container` (selector nested).
 
-### Flexbox
+---
 
-**Flex shorthand:**
+## 6. Flexbox utilities
 
-| Class | CSS |
+| Class          | CSS |
 |---|---|
-| `flex-1` | `flex: 1` |
-| `flex-none` | `flex: none` |
-| `flex-auto` | `flex: auto` |
+| `flex-1`       | `flex: 1` |
+| `flex-none`    | `flex: none` |
+| `flex-auto`    | `flex: auto` |
+| `flex-row`     | `flex-direction: row` |
+| `flex-column`  | `flex-direction: column` |
+| `flex-row-reverse`    | `flex-direction: row-reverse` |
+| `flex-column-reverse` | `flex-direction: column-reverse` |
+| `flex-wrap`    | `flex-wrap: wrap` |
+| `flex-nowrap`  | `flex-wrap: nowrap` |
+| `flex-grow-0` / `flex-grow-1`     | `flex-grow: 0 / 1` |
+| `flex-shrink-0` / `flex-shrink-1` | `flex-shrink: 0 / 1` |
 
-**Direction:**
-```
-flex-row   flex-column   flex-row-reverse   flex-column-reverse
-```
+**align-items:** `align-items-start`, `align-items-end`, `align-items-center`, `align-items-baseline`, `align-items-stretch`.
 
-**Wrap:**
-```
-flex-wrap   flex-nowrap
-```
+**align-self:** `align-self-start`, `align-self-end`, `align-self-center`, `align-self-stretch`, `align-self-auto`.
 
-**Grow & shrink:**
-```
-flex-grow-0   flex-grow-1   flex-shrink-0   flex-shrink-1
-```
+**align-content:** `align-content-start`, `align-content-end`, `align-content-center`, `align-content-between`, `align-content-around`, `align-content-stretch`.
 
-**Align items:**
-```
-align-items-start   align-items-end   align-items-center
-align-items-baseline   align-items-stretch
-```
+**justify-content:** `justify-content-start`, `justify-content-end`, `justify-content-center`, `justify-content-between`, `justify-content-around`, `justify-content-evenly`.
 
-**Align self:**
-```
-align-self-start   align-self-end   align-self-center
-align-self-stretch   align-self-auto
-```
+---
+
+## 7. Spacing
+
+### 7.1 Margin / Padding (px-based, 0–200)
 
-**Align content:**
 ```
-align-content-start   align-content-end   align-content-center
-align-content-between   align-content-around   align-content-stretch
+m-{n}   mt-{n}   mr-{n}   mb-{n}   ml-{n}   mx-{n}   my-{n}
+p-{n}   pt-{n}   pr-{n}   pb-{n}   pl-{n}   px-{n}   py-{n}
 ```
 
-**Justify content:**
+Ví dụ: `m-0`, `mt-8`, `px-16`, `py-24`, `mb-4`.
+
+**Auto margin:** `m-auto`, `mt-auto`, `mr-auto`, `mb-auto`, `ml-auto`, `mx-auto`, `my-auto`.
+
+### 7.2 Gap (px-based, 0–200)
+
 ```
-justify-content-start   justify-content-end   justify-content-center
-justify-content-between   justify-content-around   justify-content-evenly
+gap-{n}   gap-x-{n}   gap-y-{n}
 ```
 
+Ví dụ: `gap-8`, `gap-x-16`, `gap-y-4`.
+
 ---
 
-### Display
+## 8. Sizing
 
-| Class | CSS |
+### 8.1 Width / Height theo px (0–200)
+
+```
+w-{n}   h-{n}
+```
+
+### 8.2 Width / Height theo %/keyword
+
+| Class           | CSS |
 |---|---|
-| `d-none` | `display: none` |
-| `d-block` | `display: block` |
-| `d-inline` | `display: inline` |
-| `d-inline-block` | `display: inline-block` |
-| `d-flex` | `display: flex` |
-| `d-inline-flex` | `display: inline-flex` |
-| `d-grid` | `display: grid` |
+| `w-full` / `w-100` | `width: 100%` (`w-100` là alias của `w-full`) |
+| `w-auto`        | `width: auto` |
+| `w-screen`      | `width: 100vw` |
+| `w-fit`         | `width: fit-content` |
+| `h-full` / `h-100` | `height: 100%` |
+| `h-auto`        | `height: auto` |
+| `h-screen`      | `height: 100vh` |
+| `h-fit`         | `height: fit-content` |
+| `min-h-full`    | `min-height: 100%` |
+| `min-h-screen`  | `min-height: 100vh` |
+| `min-w-full`    | `min-width: 100%` |
+| `max-h-full`    | `max-height: 100%` |
+| `max-w-full`    | `max-width: 100%` |
 
 ---
 
-### Gap
+## 9. Border & radius
+
+### 9.1 Border-radius (px-based, 0–200)
+
+```
+rounded-{n}        // border-radius: {n}px
+rounded-full       // border-radius: 9999px (pill / circle)
+```
+
+### 9.2 Border utilities
 
-Hệ thống gap theo đơn vị **px**, range từ 0 đến 200.
+Border color default = `var(--sd-black200)`.
 
-| Class | CSS |
+| Class            | CSS |
 |---|---|
-| `gap-{n}` | `gap: npx` |
-| `gap-x-{n}` | `column-gap: npx` |
-| `gap-y-{n}` | `row-gap: npx` |
+| `border`         | `border: 1px solid var(--sd-black200)` |
+| `border-0`       | `border: 0` |
+| `border-top`     | `border-top: 1px solid var(--sd-black200)` |
+| `border-bottom`  | `border-bottom: 1px solid var(--sd-black200)` |
+| `border-left`    | `border-left: 1px solid var(--sd-black200)` |
+| `border-right`   | `border-right: 1px solid var(--sd-black200)` |
 
-Ví dụ: `gap-8`, `gap-x-16`, `gap-y-4`
+Đổi màu border: kết hợp `.border` với `.border-{token}` (xem §3.2).
 
 ---
 
-### Typography
+## 10. Display, position, overflow, visibility
 
-#### Design token classes
+### 10.1 Display
 
-Hệ thống typography theo quy ước `T{size}{weight}` — `M` = Medium (500), `R` = Regular (400).
+| Class            | CSS |
+|---|---|
+| `d-none`         | `display: none` |
+| `d-block`        | `display: block` |
+| `d-inline`       | `display: inline` |
+| `d-inline-block` | `display: inline-block` |
+| `d-flex`         | `display: flex` |
+| `d-inline-flex`  | `display: inline-flex` |
+| `d-grid`         | `display: grid` |
 
-| Class | Font size | Weight | Line height |
-|---|---|---|---|
-| `T48M` / `T48R` | 48px | 500 / 400 | 56px |
-| `T32M` / `T32R` | 32px | 500 / 400 | 48px |
-| `T24M` / `T24R` | 24px / 20px | 500 / 400 | 28px |
-| `T20M` / `T20R` | 20px | 500 / 400 | 28px |
-| `T18M` / `T18R` | 18px | 500 / 400 | 28px |
-| `T16M` / `T16R` | 16px | 500 / 400 | 24px |
-| `T14M` / `T14R` | 14px | 500 / 400 | 20px |
-| `T12M` / `T12R` | 12px | 500 / 400 | 16px |
-| `T10M` / `T10R` | 10px | 500 / 400 | 12px |
-
-#### Font-size utilities (px-based, 0–200)
+### 10.2 Position
 
 ```
-fs-0   fs-12   fs-14   fs-16   ...   fs-200
+position-relative   position-absolute   position-fixed
+position-sticky     position-static
 ```
 
-#### Font-weight utilities
+### 10.3 Overflow
+
+| Class               | CSS |
+|---|---|
+| `overflow-auto`     | `overflow: auto` |
+| `overflow-hidden`   | `overflow: hidden` |
+| `overflow-visible`  | `overflow: visible` |
+| `overflow-scroll`   | `overflow: scroll` |
+| `overflow-x-auto`   | `overflow-x: auto` |
+| `overflow-y-auto`   | `overflow-y: auto` |
+
+### 10.4 Visibility
+
+| Class       | CSS |
+|---|---|
+| `visible`   | `visibility: visible` |
+| `invisible` | `visibility: hidden` |
+
+---
+
+## 11. Cursor, vertical-align, misc
+
+**Vertical-align:**
 
 ```
-font-weight-light    (300)
-font-weight-normal   (400)
-font-weight-medium   (500)
-font-weight-bold     (600)
-font-weight-bolder   (700)
+align-middle   align-top   align-bottom   align-baseline
 ```
 
-#### Text alignment
+**Cursor:**
 
 ```
-text-left   text-center   text-right   text-justify
+cursor-pointer   cursor-default   cursor-not-allowed
 ```
 
-#### Text wrapping & overflow
+---
 
-| Class | CSS |
-|---|---|
-| `text-wrap` | `white-space: normal` |
-| `text-nowrap` | `white-space: nowrap` |
-| `text-ellipsis` | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` |
-| `text-break` | `overflow-wrap: break-word; word-break: break-word` |
+## 12. Elevation (`mat-elevation-z0`–`z8`)
 
-#### Text transform
+CSS shadow tĩnh, tương đương Angular Material `mat.elevation()` mixin nhưng **không cần** import Material SCSS.
 
-```
-text-uppercase   text-lowercase   text-capitalize
-```
+| Class                | Dùng cho |
+|---|---|
+| `mat-elevation-z0`   | Reset shadow |
+| `mat-elevation-z1`   | Card, chip |
+| `mat-elevation-z2`   | Button raised |
+| `mat-elevation-z3`   | Card hover |
+| `mat-elevation-z4`   | App bar |
+| `mat-elevation-z5`   | — |
+| `mat-elevation-z6`   | Floating action button |
+| `mat-elevation-z7`   | — |
+| `mat-elevation-z8`   | Dialog, drawer |
 
 ---
 
-### Overflow
+## 13. Reset / Reboot baseline
+
+`_base.scss` chạy trước mọi utility, thiết lập rendering chuẩn:
 
-| Class | CSS |
+| Rule | Mục đích |
 |---|---|
-| `overflow-auto` | `overflow: auto` |
-| `overflow-hidden` | `overflow: hidden` |
-| `overflow-visible` | `overflow: visible` |
-| `overflow-scroll` | `overflow: scroll` |
-| `overflow-x-auto` | `overflow-x: auto` |
-| `overflow-y-auto` | `overflow-y: auto` |
+| `*, *::before, *::after { box-sizing: border-box }` | Bắt buộc — thiếu là layout lệch |
+| `html { -webkit-text-size-adjust: 100%; -webkit-tap-highlight-color: transparent; line-height: 1.15 }` | iOS rotation + ẩn tap highlight |
+| `body { font-family: Roboto, 'Helvetica Neue', Arial, sans-serif; font-size: 14px; line-height: 1.5; color: #212529 }` | Baseline typography |
+| `h1…h6` | `margin-top: 0; margin-bottom: 0.5rem` |
+| `p, ol, ul, dl` | `margin-top: 0; margin-bottom: 1rem` |
+| `a { color: #007bff; text-decoration: none }`, `a:hover { text-decoration: underline }` | Link mặc định |
+| `label { display: inline-block; margin-bottom: 0.5rem }` | Form layout (mat-checkbox override ở `core/form.scss`) |
+| `button { border-radius: 0 }`, `button:focus:not(:focus-visible) { outline: 0 }` | Reset native button |
+| `table { border-collapse: collapse }` | Tránh double border |
+| `th { font-weight: 600; text-align: inherit }` | Bỏ bold native browser |
+| `textarea { overflow: auto; resize: vertical }` | Bỏ scrollbar dọc mặc định IE, chỉ resize chiều dọc |
+| `[role="button"] { cursor: pointer }` | A11y |
+| `[hidden] { display: none !important }` | IE10 fallback |
 
 ---
 
-### Position
+## 14. Custom theme
 
+Trong `styles.scss` của host app, gọi `sd.theme()` để override màu, sau đó cấu hình Angular Material M2 palette tương ứng:
+
+```scss
+@use '@sd-angular/core/assets/scss/themes/default' as sd;
+@use '@angular/material' as mat;
+@include mat.core();
+
+html {
+  @include sd.theme(
+    (
+      primary:         #AE7129,
+      primary-light:   #F4F2F1,
+      primary-dark:    #6B4414,
+    )
+  );
+}
+
+// --- Angular Material M2 palette ---
+
+$custom-primary-palette: mat.m2-define-palette((
+  50: #F4F2F1, 100: #E7E1DA, 200: #DAC8B4, 300: #D1AC80, 400: #CD9450,
+  500: #AE7129, 600: #8D5A1E, 700: #6B4414, 800: #4B2F0E, 900: #34210A,
+  contrast: ( 600: white, 700: white, 800: white, 900: white )
+));
+
+$custom-accent-palette: mat.m2-define-palette((
+  50: #F1F3F1, 100: #DCE5DD, 200: #BBD3BC, 300: #8FC291, 400: #67B76A,
+  500: #4CAF50, 600: #3A8C3D, 700: #29692C, 800: #1C471E, 900: #132F14,
+  contrast: ( 700: white, 800: white, 900: white )
+));
+
+$custom-warn-palette: mat.m2-define-palette((
+  50: #F5F0F0, 100: #EAD9D6, 200: #E4B0AA, 300: #E6786B, 400: #EE4430,
+  500: #F82C13, 600: #D11801, 700: #9A1100, 800: #680B00, 900: #440700,
+  contrast: ( 600: white, 700: white, 800: white, 900: white )
+));
+
+$custom-theme: mat.m2-define-light-theme((
+  color:   ( primary: $custom-primary-palette, accent: $custom-accent-palette, warn: $custom-warn-palette ),
+  density: -3,
+));
+
+@include mat.all-component-themes($custom-theme);
 ```
-position-relative   position-absolute   position-fixed
-position-sticky     position-static
-```
+
+> `sd.theme()` chỉ cần khai báo những token muốn override — token không khai báo giữ default.
+> Cả `sd.theme()` và `mat.all-component-themes()` **phải** gọi trong `styles.scss`, không phải component SCSS.
 
 ---
 
-### Elevation
+## 15. Fonts & images shipped
+
+### 15.1 Fonts
+
+`fonts.scss` declare `@font-face` cho 3 family — host app **không cần** thêm Google Fonts link.
 
-CSS shadow tĩnh tương đương Angular Material `mat-elevation-z{n}`.
+| Family | Variants | File path |
+|---|---|---|
+| Roboto | regular (400), 500, 600, italic | `assets/fonts/roboto/roboto-v50-latin_vietnamese-*.woff2` (4 file, latin + vietnamese subset) |
+| Material Icons | regular + outlined | `assets/fonts/material-icons/{material-icons-v145,material-icons-outlined-v110}-latin-regular.woff2` |
+| Material Symbols | regular | `assets/fonts/material-symbols/material-symbols-v29-latin-regular.woff2` |
 
-| Class | Dùng cho |
+### 15.2 Image assets (18 SVG illustrations)
+
+Tham chiếu qua `core/image.scss` utility hoặc trực tiếp `assets/images/<name>.svg`:
+
+| File                       | Dùng cho |
 |---|---|
-| `mat-elevation-z0` | Reset shadow |
-| `mat-elevation-z1` | Card, chip |
-| `mat-elevation-z2` | Button raised |
-| `mat-elevation-z3` | Card hover |
-| `mat-elevation-z4` | App bar |
-| `mat-elevation-z5` | — |
-| `mat-elevation-z6` | Floating action button |
-| `mat-elevation-z7` | — |
-| `mat-elevation-z8` | Dialog, drawer |
+| `coming-soon.svg`          | Trang chưa sẵn sàng |
+| `data-empty.svg`           | Empty state cho table / list |
+| `expired.svg`              | Session expired |
+| `file-error.svg`           | Upload file lỗi |
+| `filter-empty.svg`         | Không kết quả khớp filter |
+| `filter-required.svg`      | Yêu cầu chọn filter trước khi load data |
+| `forbidden.svg`            | 403 Forbidden |
+| `image-error.svg`          | Image load fail |
+| `maintenance.svg`          | Đang bảo trì |
+| `not-found.svg`            | 404 Not Found |
+| `offline.svg`              | Mất mạng |
+| `submitted.svg`            | Form gửi thành công |
+| `success.svg`              | Generic success |
+| `unauthorized.svg`         | 401 Unauthorized |
+| `unknown-error.svg`        | 500 / fallback |
 
 ---
 
-### Misc
+## 16. What is NOT shipped
 
-**Vertical align:**
-```
-align-middle   align-top   align-bottom   align-baseline
-```
+Để AI agent không sinh class lạ:
 
-**Cursor:**
-```
-cursor-pointer   cursor-default   cursor-not-allowed
-```
+- ❌ **Không có Bootstrap, Tailwind, Bulma, Foundation.** Tất cả utility ở §3–§13 là code thuần SCSS của `@sd-angular/core`. Class như `.btn`, `.btn-primary`, `.card`, `.alert`, `.navbar`, `.form-control`, `.input-group`, `.modal`, `.dropdown`, `.list-group`, `.breadcrumb`, `.carousel`, `.popover`, `.tooltip`, `.progress`, `.spinner-border`, `.badge` (Bootstrap) **KHÔNG tồn tại**.
+- ❌ **Không có Tailwind escape syntax** (`md:flex`, `hover:bg-red-500`, `text-[14px]`…). Responsive class duy nhất là `col-sm-*` / `col-md-*` / `col-lg-*` / `col-xl-*` ở §5.1.
+- ❌ **Không có dark mode token** sẵn — phải tự khai báo nếu cần.
+- ❌ **Không có animation utility class** (kiểu `.fade`, `.slide-in`). Animation handle qua Angular `[@trigger]` hoặc CSS riêng của component.
+- ❌ **Không sinh class theo px arbitrary** — `m-{n}`, `p-{n}`, `w-{n}`, `h-{n}`, `fs-{n}`, `gap-{n}`, `rounded-{n}` chỉ chạy từ **0 → 200** integer. Cần `w-250` thì phải tự viết SCSS hoặc dùng inline style.
+- ❌ **Không có shorthand position** (kiểu `top-0`, `left-50`). Set `position-absolute` rồi viết CSS riêng cho offset.
+- ❌ **Component selector không phải utility class.** `sd-button`, `sd-input`, `sd-anchor`… là Angular component (xem `components/*/sd-*.md`), không phải CSS class.
 
-**Visibility:**
+### Migration check khi đọc code cũ
 
-| Class | CSS |
+| Class cũ (Bootstrap) | Thay thế bằng |
 |---|---|
-| `visible` | `visibility: visible` |
-| `invisible` | `visibility: hidden` |
+| `d-flex`             | `d-flex` (giữ nguyên — đã port) |
+| `text-center`        | `text-center` (giữ nguyên) |
+| `text-truncate`      | `text-ellipsis` |
+| `font-weight-normal` | `font-weight-normal` (giữ nguyên) |
+| `mt-2` / `mt-3` …    | `mt-8` / `mt-16` … (px-based 0–200, không phải multiplier 4) |
+| `pl-2`               | `pl-8` (đổi đơn vị) |
+| `w-100`              | `w-100` hoặc `w-full` |
+| `border-secondary`   | `border-secondary` (vẫn có — secondary là token màu, không phải utility riêng) |
+| `btn`, `btn-primary` | dùng `<sd-button [color]="primary">` |
+| `form-control`       | dùng `<sd-input>` / `<sd-select>` … |
+| `alert`              | dùng `<sd-notify>` service |
+| `modal`              | dùng `<sd-modal>` |
+
+> Lưu ý lớn nhất: **spacing scale đã đổi từ Bootstrap multiplier (1=4px, 2=8px…) sang px tuyệt đối**. `mb-3` trong Bootstrap = 16px; trong `@sd-angular/core` `mb-3` = **3px**. Reading code cũ cần convert (× 4) cẩn thận hoặc thay bằng `mb-16`.