# PlayingCard
Thẻ trân châu của Xì Dách Trân Châu: giá trị và biểu tượng loại trân châu ở hai góc, biểu tượng lớn ở giữa, có mặt úp hình ly trà sữa; ba cỡ thường, lớn và mini.

## Khi nào dùng
- Thẻ trên tay khách và nhà cái trong `CardHand`, hoặc thẻ lẻ trong luật chơi.
- Bộ 52 thẻ = 4 loại trân châu × 13 giá trị (2…10, J, Q, K, A). Chỉ vẽ thẻ do code chọn sẵn; không có logic chia hay xáo.
- Loại trân châu phân biệt bằng biểu tượng và tên đọc, màu chỉ là phần thêm.

## Biến thể
| Biến thể | Lớp | Dùng khi |
|---|---|---|
| Trân Châu Đen 🧋 | `tt-playcard` (mặc định) | `tc-den`: nền `card-den-bg`, chữ nâu đậm |
| Hoàng Kim 🟡 | `tt-playcard--vang` | `tc-vang`: chữ nâu cam |
| Trắng 3Q ⚪ | `tt-playcard--trang` | `tc-trang`: chữ xanh dương |
| Dâu Tây 🍓 | `tt-playcard--dau` | `tc-dau`: chữ hồng đỏ |
| Thường | `tt-playcard` | 36×52, bo 6px (`.xd-card`): thẻ của khách trên ghế |
| Lớn | `tt-playcard--large` | 40×56, bo 7px: thẻ nhà cái (`.xd-dealer-cards-wrap .xd-card`) |
| Mini | `tt-playcard--mini` | 28×40: ghế hẹp có 5 thẻ (Ngũ Linh); bổ sung của design system |
| Úp | `is-down` | Mặt ẩn, lưng nâu có 🧋 (`.xd-card.face-down`) |

## Cấu trúc
```html
<span class="tt-playcard tt-playcard--dau" role="img" aria-label="Trân Châu Dâu Tây A" data-label="Trân Châu Dâu Tây A">
  <span class="tt-playcard__face" aria-hidden="true">
    <span class="tt-playcard__top"><span class="tt-playcard__val">A</span><span class="tt-playcard__pip">🍓</span></span>
    <span class="tt-playcard__suit">🍓</span>
    <span class="tt-playcard__bottom"><span class="tt-playcard__val">A</span></span>
  </span>
  <span class="tt-playcard__back" aria-hidden="true">🧋</span>
</span>
```
Tên đọc theo game (`title`): "<tên loại> <giá trị>", ví dụ "Trân Châu Đen 7", "Trân Châu Hoàng Kim 10". Mặt và lưng luôn cùng có trong markup để `flip()` không phải dựng lại DOM. `__pip` là biểu tượng nhỏ ở góc (`.xd-card-mini-suit`).

## Trạng thái
| Trạng thái | Hiệu ứng |
|---|---|
| Ngửa | Nền và viền theo loại (`card-<loại>-bg/-line`), bóng nhẹ |
| `is-down` | Gradient nâu `cardback-hi` → `cardback-lo`, viền 1.5px `cardback-line`, mặt ẩn, nhãn đọc "Thẻ trân châu úp" |
| Trong `CardHand` | Rê chuột nhấc thẻ lên 4px (do `tt-cardhand__slot`) |

## Hành vi JS
`TTMU.playingCard(el)` gắn một lần (đánh dấu `data-tt-bound="1"`, gắn lần hai trả về `null`) và trả về `{ faceDown, flip(), setFaceDown(flag), destroy() }`. Chỉ hiển thị, không có callback.

```js
var card = TTMU.playingCard(document.querySelector('.tt-playcard'));
card.flip();            // úp ↔ ngửa, trả về true nếu giờ đang úp
card.setFaceDown(true); // aria-label thành "Thẻ trân châu úp"; ngửa thì trả lại data-label
```
Thẻ dựng sẵn lúc úp vẫn cần `data-label` để `flip()` biết đọc tên gì khi ngửa.

## Token sử dụng
`card-den-*`, `card-vang-*`, `card-trang-*`, `card-dau-*` (mỗi loại `-bg`, `-ink`, `-line`), `cardback-hi`, `cardback-lo`, `cardback-line`, `outline` (bóng), `space-4`.

## Khả năng tiếp cận
- Thẻ là `role="img"` có `aria-label` ("Trân Châu Đen 7", "Thẻ trân châu úp"); phần bên trong `aria-hidden` để không đọc lặp.
- Loại trân châu phân biệt bằng biểu tượng 🧋🟡⚪🍓, chữ giá trị và tên đọc, không chỉ bằng màu.
- Ở Tương phản cao chữ thẻ đạt từ 7:1 trên nền thẻ, viền thẻ đạt 3:1 để thẻ tách khỏi nền trắng.
- Thẻ không tự nhận focus; thao tác là việc của khối chứa nó.

## Nên / Không nên
| Nên | Không nên |
|---|---|
| Ghi `aria-label` và `data-label` bằng "<tên loại> <giá trị>" | Để trình đọc đọc từng emoji rời |
| Giữ cả biểu tượng lẫn màu theo loại | Chỉ phân biệt loại bằng màu |
| Dùng `--mini` khi ghế ~95px có 4–5 thẻ | Tự thu nhỏ bằng `transform: scale` |

## Nguồn
`.xd-card`, `.xd-card.tc-den|tc-vang|tc-trang|tc-dau`, `.xd-card-top`, `.xd-card-val`, `.xd-card-mini-suit`, `.xd-card-suit`, `.xd-card-bottom`, `.xd-card.face-down`, `.xd-dealer-cards-wrap .xd-card` — css/xidach.css; `SUITS`, `createDeck()`, `renderCard()` trong js/xidach.js (bốn loại id, icon, name, bg, color; title "Thẻ trân châu úp").
- Màu chữ, viền và `bg` theo loại đổi sang token `card-<loại>-bg/ink/line` (bốn theme gốc giữ nguyên hex của game; Tương phản cao đậm hơn cho chữ và viền). Gradient lưng `#78350f` → `#451a03` và viền `#d97706` đổi sang `cardback-*`.
- `style="background:…"` nội tuyến của game thành lớp `--vang|--trang|--dau`; `.xd-card:hover` (nhấc 4px) chuyển sang `tt-cardhand__slot`; hai `!important` của thẻ úp bỏ đi.
- Cỡ `--mini` là bổ sung của design system.