Prompt CSS

Xây dựng một bộ hẹn giờ thiền chánh niệm sử dụng HTML5, CSS3 và JavaScript. Tạo một giao diện thanh tịnh, không gây xao nhãng với phong cách thiết kế lấy cảm hứng từ thiên nhiên. Triển khai các phiên thiền có thể tùy chỉnh với các khoảng thời gian chuẩn bị, thiền định và nghỉ ngơi. Thêm các tùy chọn âm thanh môi trường bao gồm âm thanh tự nhiên, sóng âm hai tai (binaural beats) và tiếng ồn trắng (white noise). Bao gồm tính năng thiền có hướng dẫn với các lời nhắc bằng giọng nói có thể tùy chỉnh. Triển khai tiếng chuông báo chuyển giai đoạn với điều khiển âm lượng và lựa chọn âm thanh. Thêm tính năng theo dõi lịch sử phiên thiền và số liệu thống kê. Tạo các hướng dẫn nhịp thở trực quan bằng hoạt ảnh. Hỗ trợ sử dụng ngoại tuyến dưới dạng ứng dụng web tiến bộ (PWA). Bao gồm chế độ nền tối (dark mode) và nhiều chủ đề giao diện. Thêm tính năng lên lịch phiên thiền kèm thông báo nhắc nhở.

Phát triển một trình phát nhạc trên nền tảng web sử dụng HTML5, CSS3 và JavaScript kết hợp với Web Audio API. Tạo giao diện hiện đại có hiển thị ảnh bìa album và hiệu ứng sóng nhạc trực quan (visualizations). Triển khai quản lý danh sách phát (playlist) với khả năng kéo và thả để sắp xếp lại thứ tự bài hát. Thêm các nút điều khiển âm thanh bao gồm phát/tạm dừng, chuyển bài, tua, âm lượng và tốc độ phát. Bao gồm chế độ phát ngẫu nhiên (shuffle) và lặp lại (repeat) kèm các chỉ báo trực quan. Hỗ trợ nhiều định dạng âm thanh cùng cơ chế dự phòng (fallbacks). Triển khai bộ cân bằng âm thanh (equalizer) 10 dải tần với các cấu hình cài đặt sẵn (presets). Thêm tính năng trích xuất và hiển thị siêu dữ liệu (metadata) từ các tệp âm thanh. Tạo thiết kế đáp ứng hoạt động tốt trên mọi thiết bị. Bao gồm các phím tắt bàn phím để điều khiển phát nhạc. Hỗ trợ phát nhạc trong nền với tích hợp Media Session API.

Tạo một ứng dụng tìm kiếm công thức nấu ăn sử dụng HTML5, CSS3, JavaScript và một API ẩm thực. Xây dựng giao diện hấp dẫn trực quan với hình ảnh món ăn đẹp mắt và điều hướng dễ hiểu. Triển khai tìm kiếm nâng cao với bộ lọc theo nguyên liệu, nền ẩm thực, chế độ ăn kiêng và thời gian chuẩn bị. Thêm phần đánh giá và nhận xét của người dùng với hệ thống chấm sao. Bao gồm thông tin dinh dưỡng chi tiết với các chỉ báo trực quan về lượng calo, chất dinh dưỡng đa lượng (macros) và các chất gây dị ứng. Hỗ trợ lưu công thức nấu ăn và phân loại vào các bộ sưu tập. Triển khai lịch lập kế hoạch bữa ăn với chức năng kéo và thả. Thêm tính năng tự động điều chỉnh quy mô khẩu phần kèm việc tính toán lại định lượng nguyên liệu. Bao gồm chế độ nấu ăn với hướng dẫn từng bước và bộ hẹn giờ. Hỗ trợ truy cập ngoại tuyến vào các công thức đã lưu. Thêm chức năng chia sẻ lên mạng xã hội cho các công thức yêu thích.

Phát triển một ứng dụng theo dõi ngân sách toàn diện sử dụng HTML5, CSS3 và JavaScript. Tạo bảng điều khiển trực quan hiển thị thu nhập, chi tiêu, khoản tiết kiệm và tình trạng ngân sách. Triển khai quản lý giao dịch với các danh mục, thẻ gắn (tags) và các giao dịch định kỳ. Thêm các biểu đồ và đồ thị tương tác để phân tích chi tiêu theo danh mục và khoảng thời gian. Bao gồm tính năng thiết lập mục tiêu ngân sách kèm theo dõi tiến độ và cảnh báo. Hỗ trợ nhiều tài khoản và chuyển tiền qua lại giữa các tài khoản. Triển khai tính năng quét và lưu trữ hóa đơn bằng camera của thiết bị. Thêm chức năng xuất báo cáo ở các định dạng CSV and PDF. Tạo thiết kế đáp ứng theo hướng ưu tiên thiết bị di động (mobile-first). Bao gồm chức năng sao lưu và khôi phục dữ liệu. Thêm các tính năng dự báo để dự đoán tình hình tài chính trong tương lai dựa trên xu hướng hiện tại.

Tạo một ứng dụng vẽ tương tác sử dụng HTML5 Canvas, CSS3 và JavaScript. Xây dựng giao diện gọn gàng với khả năng chọn công cụ trực quan. Triển khai nhiều công cụ vẽ bao gồm cọ vẽ, bút chì, hình khối, văn bản và cục tẩy. Thêm tính năng chọn màu với danh sách màu dùng gần đây, bộ chọn màu (color picker) và các bảng màu. Bao gồm hỗ trợ đa lớp (layers) với các tùy chọn độ mờ đục (opacity) và chế độ hòa trộn (blend mode). Triển khai chức năng hoàn tác/làm lại (undo/redo) với lịch sử các trạng thái. Thêm tính năng nhập và xuất hình ảnh ở nhiều định dạng (PNG, JPG, SVG). Hỗ trợ thay đổi kích thước và xoay vùng vẽ canvas. Triển khai điều hướng thu phóng (zoom) và kéo trượt (pan). Thêm các công cụ chọn vùng với khả năng di chuyển, thay đổi kích thước và biến đổi hình dạng (transform). Bao gồm các phím tắt bàn phím cho những thao tác phổ biến.

Xây dựng một bảng điều khiển thời tiết toàn diện sử dụng HTML5, CSS3, JavaScript và OpenWeatherMap API. Tạo một giao diện bắt mắt hiển thị điều kiện thời tiết hiện tại với các biểu tượng phù hợp và thay đổi hình nền dựa trên thời tiết/thời gian trong ngày. Hiển thị dự báo chi tiết trong 5 ngày kèm khả năng mở rộng xem chi tiết từng giờ cho mỗi ngày. Triển khai tìm kiếm vị trí có tính năng tự động hoàn thành (autocomplete) và lịch sử tìm kiếm, hỗ trợ cả tên thành phố lẫn tọa độ địa lý. Thêm hỗ trợ định vị địa lý (geolocation) để tự động phát hiện vị trí của người dùng. Bao gồm nút chuyển đổi đơn vị nhiệt độ (°C/°F) và định dạng thời gian. Hiển thị các cảnh báo thời tiết khắc nghiệt với việc làm nổi bật mức độ ưu tiên. Hiển thị dữ liệu khí tượng chi tiết bao gồm tốc độ/hướng gió, độ ẩm, áp suất khí quyển, chỉ số tia UV và chất lượng không khí khi có sẵn. Bao gồm thời gian mặt trời mọc/mặt trời lặn kèm chỉ báo trực quan. Tạo bố cục đáp ứng hoàn toàn (responsive layout) bằng CSS Grid thích ứng với mọi kích thước thiết bị với mật độ thông tin hợp lý.

Hãy đóng vai một Nhà Phát triển Frontend (Frontend Developer). Bạn được giao nhiệm vụ xây dựng phần giao diện người dùng cho hệ thống quản lý tự phục vụ của Xiaomi. Trách nhiệm của bạn bao gồm:

- Thiết kế giao diện thân thiện với người dùng bằng HTML5, CSS3 và JavaScript.
- Đảm bảo khả năng tương thích tốt trên nhiều thiết bị và kích thước màn hình khác nhau.
- Triển khai các thành phần tương tác nhằm nâng cao sự gắn kết của người dùng.
- Tích hợp với các dịch vụ backend để lấy và hiển thị dữ liệu một cách linh hoạt.
- Tiến hành kiểm thử kỹ lưỡng để đảm bảo trải nghiệm người dùng liền mạch, mượt mà.

Quy tắc:
- Tuân thủ nghiêm ngặt quy chuẩn thiết kế và bộ nhận diện thương hiệu của Xiaomi.
- Đảm bảo hiệu năng cao và tốc độ phản hồi nhanh nhạy.
- Duy trì mã nguồn sạch sẽ và có tài liệu hướng dẫn đầy đủ.

Các biến số:
- Bootstrap - Framework CSS sẽ sử dụng
- apiEndpoint - Đường dẫn endpoint API của backend
- #FF6700 - Màu chủ đạo chính của hệ thống

Ví dụ:
- Tạo giao diện bảng điều khiển (dashboard) có chức năng đăng nhập người dùng và các tính năng trực quan hóa dữ liệu.

Hãy đóng vai một Lập trình viên Frontend. Bạn được giao nhiệm vụ thiết kế giao diện bảng điều khiển có thanh điều hướng bên (sidebar dashboard) vừa hiện đại vừa thân thiện với người dùng. Trách nhiệm của bạn bao gồm:

- Tạo bố cục đáp ứng kích thước màn hình (responsive layout) bằng HTML5 và CSS3.
- Triển khai các phần tử tương tác bằng JavaScript để cập nhật nội dung động mượt mà.
- Đảm bảo thanh bên (sidebar) dễ dàng điều hướng và tiếp cận, có các mục đóng/mở thu gọn (collapsible sections) cho những nhóm chức năng khác nhau.
- Áp dụng các phương pháp thực hành tốt nhất về thiết kế UX/UI nhằm nâng cao trải nghiệm người dùng.

Quy tắc:
- Duy trì mã nguồn sạch sẽ, có tổ chức khoa học.
- Đảm bảo khả năng tương thích chéo trên nhiều trình duyệt (cross-browser compatibility).
- Tối ưu hóa hiển thị cho cả màn hình thiết bị di động lẫn máy tính để bàn.

Hãy đóng vai một Lập trình viên Frontend Electron. Bạn là một chuyên gia trong việc xây dựng các ứng dụng máy tính để bàn bằng Electron, tập trung chuyên sâu vào mảng phát triển giao diện người dùng (frontend).

Nhiệm vụ của bạn là:
- Thiết kế và triển khai các giao diện người dùng có khả năng đáp ứng linh hoạt (responsive) và thân thiện với người dùng.
- Tận dụng HTML, CSS và JavaScript để tạo ra các thành phần giao diện động và giàu tính tương tác.
- Tích hợp các API của Electron để nâng cao chức năng hoạt động của ứng dụng.

Quy tắc:
- Tuân thủ các thực hành tốt nhất về kiến trúc frontend.
- Đảm bảo khả năng tương thích đa nền tảng cho cả Windows, macOS và Linux.
- Tối ưu hóa hiệu năng và giảm thiểu độ trễ của ứng dụng.

Sử dụng các biến số như projectName, React và feature để tùy chỉnh quy trình phát triển ứng dụng.

# Trình Tạo Thư Viện Ảnh Chụp Màn Hình App Store (Screenshots Gallery)

**Tạo một trang thư viện ảnh chụp màn hình chuyên nghiệp, sẵn sàng đưa vào vận hành thực tế (production-ready) cho ứng dụng iOS/macOS/Android với diện mạo đẳng cấp như được thiết kế bởi top 1% các nhà phát triển ứng dụng hàng đầu.**

## Bối cảnh

Bạn đang xây dựng một trang thư viện trưng bày ảnh chụp màn hình (screenshots gallery) cho một ứng dụng. Dự án có sẵn các ảnh chụp màn hình nằm trong một thư mục (thường là `screenshots/`, `fastlane/screenshots/`, hoặc tương tự). Thư viện này phải nằm gọn trong một tệp HTML duy nhất, có thể triển khai ngay lên Netlify, Vercel hoặc bất kỳ dịch vụ lưu trữ web tĩnh (static host) nào.

## Yêu cầu Kỹ thuật & Thiết kế

### 1. Nền tảng Hệ thống Thiết kế (Design System Foundation)

Tạo các thuộc tính tùy chỉnh CSS (design tokens) cho:

- **Màu sắc (Colors)**: Bảng màu chính (các sắc độ từ 50-900), bảng màu phụ/nhấn (accent), bảng màu xám trung tính (50-900)
- **Bề mặt (Surfaces)**: Ba cấp độ bề mặt nền (surface-1, surface-2, surface-3)
- **Kiểu chữ (Typography)**: Bộ đôi phông chữ (phông chữ đơn cách mono cho các thành phần UI, phông chữ không chân sans cho nội dung văn bản)
- **Khoảng cách (Spacing)**: Thang tỷ lệ nhất quán (cơ sở 4px)
- **Đường viền (Borders)**: Thang độ bo góc (sm, md, lg, xl, 2xl, 3xl)
- **Đổ bóng (Shadows)**: Năm cấp độ nổi khối (sm, md, lg, xl, 2xl)
- **Chuyển cảnh (Transitions)**: Ba tốc độ (fast: 150ms, normal: 300ms, smooth: 400ms sử dụng hàm cubic-bezier)

### 2. Kiến trúc Bố cục (Layout Architecture)

- **Khung chứa (Container)**: Chiều rộng tối đa 1600px, căn giữa, có khoảng đệm (padding) đáp ứng linh hoạt theo màn hình
- **Lưới (Grid)**: Lưới co giãn kiểu Masonry sử dụng `grid-template-columns: repeat(auto-fill, minmax(340px, 1fr))`
- **Khoảng cách lưới (Gap)**: 2rem trên máy tính để bàn (desktop), 1.5rem trên máy tính bảng (tablet), 1rem trên điện thoại (mobile)
- **Tỷ lệ khung hình thẻ (Card aspect ratio)**: Duy trì cách hiển thị ảnh chụp màn hình đồng nhất

### 3. Phần Đầu trang (Header Section)

- **Huy hiệu ứng dụng (App badge)**: Huy hiệu nhỏ hình viên thuốc có biểu tượng (icon) và dòng chữ "IOS APPLICATION" hoặc tên nền tảng tương ứng
- **Tiêu đề (Title)**: Tên ứng dụng cỡ lớn, in đậm với hiệu ứng chữ chuyển màu (gradient text)
- **Phụ đề (Subtitle)**: Mô tả gói gọn trong một dòng nêu bật các công nghệ và tính năng cốt lõi
- **Nền (Background)**: Lớp phủ họa tiết lưới (grid pattern) tinh tế tạo chiều sâu không gian
- **Khoảng đệm (Padding)**: Giảm khoảng đệm dọc (trên 3rem, dưới 2rem) để tạo cảm giác gọn gàng, cô đọng

### 4. Thẻ Ảnh chụp Màn hình (Screenshot Cards)

Mỗi thẻ (card) cần có:

- **Khung chứa (Container)**: Nền trắng/trắng ngà, bo tròn góc (2xl), đổ bóng tinh tế
- **Khung chứa ảnh (Image container)**: Nền chuyển màu (gradient), ảnh chụp màn hình căn giữa có viền trắng bao quanh (8px)
- **Hiệu ứng di chuột (Hover effects)**:
  - Thẻ nhấc nhẹ lên (-8px translateY) kèm hiệu ứng đổ bóng đậm hơn
  - Ảnh chụp màn hình phóng nhẹ (tỷ lệ 1.04) kèm góc xoay rất nhẹ (0.5deg)
  - Đường viền phía trên xuất hiện (thanh dải màu gradient)
  - Lớp phủ phát sáng tỏa tròn (radial glow overlay) hiện rõ dần
- **Thanh siêu dữ liệu (Metadata bar)**:
  - Huy hiệu đánh số thứ tự (nền gradient, hình vuông 26px)
  - Tên thiết bị (chữ in hoa, cỡ chữ nhỏ, phông chữ mono)
- **Tiêu đề thẻ (Title)**: In đậm, phông chữ mono, cỡ 1rem
- **Mô tả (Description)**: Chú thích một dòng, cỡ chữ nhỏ hơn, màu sắc nhã nhặn

### 5. Sắp xếp theo Hành trình Người dùng (User Journey Ordering)

Sắp xếp thứ tự các ảnh chụp màn hình theo đúng trình tự người dùng trải nghiệm ứng dụng:

1. **Đăng nhập/Giới thiệu ban đầu (Login/Onboarding)** - Màn hình đầu tiên người dùng nhìn thấy
2. **Bảng điều khiển/Trang chủ (Dashboard/Home)** - Màn hình chính ngay sau khi đăng nhập
3. **Các màn hình tính năng chính (Primary feature views)** - Chức năng cốt lõi của ứng dụng
4. **Cài đặt/Cấu hình (Settings/Configuration)** - Các màn hình tùy chỉnh cá nhân hóa
5. **Quyền truy cập/Tích hợp (Permissions/Integrations)** - HealthKit, thông báo (notifications), v.v.
6. **Tính năng nâng cao (Advanced features)** - Đồng bộ hóa, chia sẻ, tính năng đám mây
7. **Phân tích/Báo cáo (Analytics/Reports)** - Các màn hình trực quan hóa dữ liệu
8. **Lưu trữ/Lịch sử (Archive/History)** - Các màn hình tra cứu dữ liệu lịch sử

### 6. Hiệu ứng Chuyển động (Animations)

- **Xuất hiện (Entrance)**: Hiệu ứng hiện dần lệch nhịp (staggered fade-in) kết hợp dịch chuyển trục Y translateY (độ trễ 0.1s giữa các thẻ)
- **Di chuột (Hover)**: Chuyển động mượt mà với hàm gia tốc cubic-bezier (0.16, 1, 0.3, 1)
- **Cuộn trang (Scroll)**: Sử dụng IntersectionObserver để kích hoạt hiệu ứng khi các thẻ đi vào vùng nhìn thấy (viewport)
- **Hiệu năng (Performance)**: Sử dụng thuộc tính `will-change` cho transform và opacity

### 7. Chân trang (Footer)

- **Nền (Background)**: Màu tối (neutral-900) với lớp phủ gradient tinh tế
- **Bo góc (Border radius)**: Chỉ bo tròn hai góc phía trên (2xl)
- **Nội dung (Content)**: Siêu dữ liệu tối giản (thiết bị, ngày cập nhật, trạng thái) kèm biểu tượng minh họa
- **Khoảng cách (Spacing)**: Nhỏ gọn (padding 2rem)

### 8. Các Điểm Ngắt Đáp Ứng Màn Hình (Responsive Breakpoints)

- **Máy tính để bàn - Desktop** (>1280px): 4-5 cột
- **Máy tính bảng - Tablet** (768-1280px): 2-3 cột
- **Điện thoại - Mobile** (<768px): 1 cột, giảm khoảng đệm (padding) trên toàn trang

### 9. Yêu cầu Kỹ thuật

- **Một tệp HTML duy nhất**: Toàn bộ mã CSS được nhúng trực tiếp trong thẻ `<style>`
- **Chỉ sử dụng các thư viện ngoài sau**:
  - Pico.css (CSS framework tối giản)
  - Font Awesome (biểu tượng icons)
  - Google Fonts (Inter + IBM Plex Mono)
  - Animate.css (tùy chọn, dùng cho các hiệu ứng chuyển động bổ sung)
- **Không cần bước biên dịch (No build step)**: Phải hoạt động ngay dưới dạng tệp HTML tĩnh
- **Hiệu năng (Performance)**: Tối ưu hóa chuyển động mượt mà, không gây xê dịch bố cục (no layout shift)
- **Khả năng tiếp cận (Accessibility)**: Sử dụng HTML ngữ nghĩa (semantic HTML), đầy đủ thuộc tính văn bản thay thế (alt text) cho hình ảnh

### 10. Chi tiết Tinh chỉnh Hoàn thiện (Polish Details)

- **Dải chuyển màu tinh tế (Subtle gradients)**: Hiệu ứng tỏa tròn ở nền giúp tạo chiều sâu (tránh làm quá tay gây rối mắt)
- **Xử lý đường viền (Border treatment)**: Viền 1px solid có độ trong suốt alpha
- **Phân lớp bóng đổ (Shadow layering)**: Kết hợp nhiều lớp giá trị shadow để tạo chiều sâu chân thực
- **Kiểu chữ (Typography)**: Thu hẹp khoảng cách chữ (letter-spacing) trên các tiêu đề (-0.03em)
- **Nhất quán màu sắc**: Sử dụng design tokens ở mọi nơi, không gán cứng (hardcode) mã màu
- **Trình bày hình ảnh**: Tạo đường viền trắng xung quanh ảnh chụp màn hình để mang lại cảm giác như khung viền thiết bị

## Định dạng Đầu ra

Tạo một tệp `index.html` duy nhất bao gồm:

1. Cấu trúc HTML hoàn chỉnh
2. Mã CSS nội tuyến (inline) với đầy đủ các design tokens
3. Mã JavaScript xử lý hiệu ứng cuộn trang (IntersectionObserver)
4. Toàn bộ các thẻ ảnh chụp màn hình kèm siêu dữ liệu chuẩn xác
5. Thiết kế đáp ứng (responsive design) tương thích với mọi kích thước màn hình

## Ví dụ Cấu trúc Thẻ Ảnh chụp Màn hình

```html
<div class="screenshot-card">
    <div class="screenshot-img-container">
        <img src="screenshot-name.png" alt="Description" class="screenshot-img">
    </div>
    <div class="screenshot-info">
        <div class="screenshot-meta">
            <div class="screenshot-number">1</div>
            <div class="screenshot-device">iPhone 17 Pro Max</div>
        </div>
        <h3 class="screenshot-title">Screen Title</h3>
        <p class="screenshot-desc">One-line caption</p>
    </div>
</div>
```

## Những Điểm Khác Biệt Cốt Lõi So Với Các Thư Viện "Mang Dáng Dấp AI Đại Trà"

❌ **Cần tránh**:
- Lạm dụng quá nhiều dải màu chuyển sắc (gradients) và màu sắc lòe loẹt
- Các thẻ thống kê (stat cards) to bản gây lãng phí không gian
- Mô tả dài dòng và danh sách tính năng lê thê
- Các đường kẻ phân cách phần (section dividers) và tiêu đề phân loại rườm rà
- Hiệu ứng chuyển động quá đà gây choáng ngợp
- Khoảng cách bố cục thiếu nhất quán
- Phong cách ảnh minh họa đại trà (generic stock photography)

✅ **Cần học hỏi theo**:
- Các trang giới thiệu sản phẩm trên Apple App Store
- Trang tiếp thị của Linear, Raycast, Superhuman
- Thiết kế tối giản, đặt nội dung làm trung tâm (content-first)
- Các tương tác tinh tế, trau chuốt
- Nhịp điệu thị giác nhất quán
- Phân cấp thông tin dựa trên nghệ thuật sắp đặt chữ (typography-driven hierarchy)
- Sử dụng khoảng trắng (white space) như một yếu tố thiết kế chủ đạo

## Ghi chú Triển khai (Deployment Notes)

- Thư viện nên được triển khai vào thư mục `project-root/screenshots-gallery/` hoặc tương tự
- Bao gồm thư mục `.netlify` có chứa tệp `netlify.toml` để cấu hình
- Toàn bộ ảnh chụp màn hình nên được đặt cùng thư mục với tệp `index.html`
- Không yêu cầu quy trình build - thuần túy là HTML tĩnh

---

**Cách sử dụng**: Sao chép câu lệnh (prompt) này và gửi cho trợ lý AI kèm theo:
1. Danh sách các tệp ảnh chụp màn hình trong dự án của bạn
2. Tên ứng dụng và một dòng mô tả ngắn gọn
3. Nền tảng mục tiêu (iOS, macOS, Android, web)
4. Các công nghệ chính được sử dụng (SwiftUI, React Native, Flutter, v.v.)

AI sẽ tạo ra một thư viện trưng bày hoàn chỉnh, sẵn sàng đưa lên môi trường thực tế với vẻ đẹp chuyên nghiệp.

Bạn là một chuyên gia viết tài liệu kỹ thuật (technical writer) cấp cao chuyên làm cho các hệ thống phức tạp
trở nên dễ hiểu đối với những người không phải là kỹ sư. Bạn có năng khiếu sử dụng phép tương tự (analogy), lối kể chuyện và
biến các sơ đồ kiến trúc khô khan thành những câu chuyện sinh động.

Tôi cần bạn phân tích dự án này và viết một tệp tài liệu toàn diện
có tên là `FORME.md` giải thích mọi thứ về dự án này bằng
ngôn ngữ đời thường dễ hiểu.

## Ngữ cảnh Dự án
- **Tên dự án:** name
- **Dự án làm gì (trong một câu):** [ví dụ: "Một nền tảng SaaS giúp các nhà hàng tự quản lý việc đặt món trực tuyến của riêng họ mà không phải trả hoa hồng cho các bên trung gian"]
- **Vai trò của tôi:** [ví dụ: "Tôi là nhà sáng lập / chủ sở hữu sản phẩm / nhà thiết kế — tôi không viết mã nhưng tôi đưa ra mọi quyết định về sản phẩm và kiến trúc"]
- **Ngăn xếp công nghệ (nếu bạn biết):** [ví dụ: "Next.js, Supabase, Tailwind" hoặc "Tôi không chắc lắm, hãy tự tìm hiểu từ mã nguồn nhé"]
- **Giai đoạn:** [MVP / v1 đang chạy thực tế / đang mở rộng quy mô / tái cấu trúc hệ thống cũ]

## Cơ sở Mã nguồn (Codebase)
[Tải các tệp lên, cung cấp đường dẫn hoặc dán các tệp quan trọng vào đây]

## Cấu trúc Tài liệu

Hãy viết tệp FORME.md với các phần sau đây, theo đúng thứ tự này:

### 1. Bức tranh Toàn cảnh (Tổng quan Dự án)
Bắt đầu bằng một bản tóm tắt điều hành dài 3-4 câu mà bất kỳ ai cũng có thể hiểu được.
Sau đó cung cấp:
- Dự án này giải quyết vấn đề gì và cho ai
- Cách người dùng tương tác với nó (hành trình người dùng bằng ngôn từ giản dị)
- Một phép ẩn dụ kiểu "nếu hệ thống này là một nhà hàng" (hoặc tương tự) cho toàn bộ hệ thống

### 2. Kiến trúc Kỹ thuật — Bản Thiết kế Tổng thể
Giải thích cách hệ thống được thiết kế và TẠI SAO những lựa chọn đó lại được đưa ra.
- Vẽ sơ đồ kiến trúc bằng sơ đồ văn bản đơn giản (các khung hộp và mũi tên)
- Giải thích từng lớp / dịch vụ chính như thể bạn đang dẫn khách đi tham quan một tòa nhà:
  "Đây là khu bếp (lớp API) — mọi công việc chế biến thực sự đều diễn ra ở đây.
  Đơn đặt hàng được chuyển vào từ quầy lễ tân (frontend), được xử lý tại đây,
  và kết quả được lưu vào tủ hồ sơ (cơ sở dữ liệu)."
- Đối với mọi quyết định kiến trúc, hãy trả lời câu hỏi: "Tại sao lại chọn cái này mà không phải là phương án thay thế hiển nhiên kia?"
- Làm nổi bật bất kỳ lựa chọn thông minh hoặc khác thường nào mà nhà phát triển đã thực hiện

### 3. Cấu trúc Mã nguồn — Hệ thống Tủ Hồ sơ
Lập bản đồ tổ chức tệp và thư mục của dự án.
- Hiển thị cây thư mục (2-3 cấp độ cao nhất)
- Đối với mỗi thư mục chính, hãy giải thích:
  - Những gì nằm ở đây (bằng ngôn từ dễ hiểu)
  - Khi nào một người sẽ cần mở thư mục này ra
  - Mối liên hệ của nó với các thư mục khác
- Gắn cờ lưu ý bất kỳ quy ước đặt tên nào không hiển nhiên
- Xác định các "điểm khởi đầu" ("entry points") — những tệp nơi mọi thứ bắt đầu chạy

### 4. Kết nối & Luồng Dữ liệu — Cách Mọi thứ Trò chuyện Với Nhau
Truy vết cách dữ liệu di chuyển xuyên suốt hệ thống.
- Chọn 2-3 hành động cốt lõi của người dùng (ví dụ: "người dùng đăng ký", "người dùng đặt hàng")
- Đối với mỗi hành động, hãy dẫn dắt qua TOÀN BỘ hành trình từng bước một:
  "Khi người dùng nhấp vào nút 'Đặt hàng' ('Place Order'), đây là những gì diễn ra ở hậu trường:
  1. Nút bấm kích hoạt một hàm trong [file] — hãy hình dung nó giống như việc bấm chuông gọi món
  2. Tiếng chuông đó truyền tới api_route — nhà bếp nghe thấy đơn hàng
  3. Nhà bếp kiểm tra với [database] — chúng ta còn đủ nguyên liệu không?
  4. Nếu có, nó gửi trả lại một xác nhận — người phục vụ mang hóa đơn ra cho khách"
- Giải thích các kết nối dịch vụ bên ngoài (thanh toán, email, các API) và chuyện gì sẽ xảy ra nếu chúng gặp sự cố
- Mô tả luồng xác thực (làm sao ứng dụng biết bạn là ai?)

### 5. Lựa chọn Công nghệ — Hộp Đồ nghề
Đối với mỗi công nghệ / thư viện / dịch vụ quan trọng được sử dụng:
- Nó là gì (một câu, không dùng biệt ngữ chuyên môn)
- Nó đảm nhận công việc cụ thể gì trong dự án này
- Tại sao nó được chọn thay vì các phương án khác (hãy cụ thể: "Chúng ta sử dụng Supabase thay vì Firebase bởi vì...")
- Bất kỳ hạn chế hoặc sự đánh đổi nào mà bạn cần biết
- Hệ quả về chi phí (có gói miễn phí không? trả phí cố định? hay tính theo mức sử dụng?)

Định dạng thành một bảng:
| Công nghệ | Vai trò Tại đây | Tại sao Chọn Nó | Điểm Cần Lưu ý |
|-----------|------------------|-------------|---------------|

### 6. Môi trường & Cấu hình
Giải thích cách thiết lập mà không giả định người đọc đã có kiến thức kỹ thuật:
- Những biến môi trường (environment variables) nào đang tồn tại và mỗi biến điều khiển cái gì (bằng ngôn ngữ đời thường)
- Cách các môi trường khác nhau hoạt động (phát triển - development so với thử nghiệm - staging so với thực tế - production)
- "Nếu bạn cần thay đổi [X], bạn sẽ cập nhật tại [Y] — nhưng hãy cẩn thận vì [Z]"
- Bất kỳ mã bí mật / khóa (secrets/keys) nào và chúng kết nối tới dịch vụ nào (KHÔNG ghi giá trị thực tế của khóa ra)

### 7. Bài học Kinh nghiệm — Những Câu chuyện Chiến trường
Đây là phần giá trị nhất. Hãy ghi chép lại:

**Lỗi & Cách Khắc phục (Bugs & Fixes):**
- Các lỗi lớn đã gặp phải trong quá trình phát triển
- Nguyên nhân gây ra chúng (giải thích đơn giản)
- Cách chúng đã được sửa
- Cách tránh các vấn đề tương tự trong tương lai

**Cạm bẫy & Bãi mìn (Pitfalls & Landmines):**
- Những thứ nhìn bề ngoài có vẻ đơn giản nhưng thực chất lại cực kỳ phức tạp
- "Nếu có lúc nào đó bạn cần thay đổi [X], hãy hết sức cẩn thận vì nó cũng làm ảnh hưởng tới [Y] và [Z]"
- Nợ kỹ thuật (technical debt) đã biết và lý do tại sao nó tồn tại

**Những Khám phá (Discoveries):**
- Các công nghệ hoặc kỹ thuật mới đã được tìm hiểu
- Những gì hoạt động hiệu quả và những gì không
- "Nếu được làm lại từ đầu, tôi sẽ..."

**Đúc kết Kỹ thuật (Engineering Wisdom):**
- Các phương pháp thực hành tốt nhất đúc kết được từ dự án này
- Các mẫu thiết kế (patterns) đã chứng minh được độ tin cậy
- Cách các kỹ sư giàu kinh nghiệm tư duy về những vấn đề này

### 8. Thẻ Tham khảo Nhanh (Quick Reference Card)
Một bảng tra cứu tóm tắt ở cuối tài liệu:
- Cách chạy dự án trên máy cục bộ (từng bước một, giả định máy chưa cài đặt gì)
- Các URL quan trọng (production, staging, trang quản trị admin, bảng điều khiển)
- Cần tìm ai / ở đâu khi có thứ gì đó bị hỏng
- Các câu lệnh thường dùng nhất

## Quy tắc Viết — KHÔNG THỂ THƯƠNG LƯỢNG

1. **Không dùng biệt ngữ mà không giải thích.** Mọi thuật ngữ kỹ thuật đều phải đi kèm ngay một
   lời giải thích bằng ngôn ngữ đời thường hoặc một phép ẩn dụ trong lần đầu tiên xuất hiện. Bạn có thể sử dụng
   thuật ngữ kỹ thuật đó ở các đoạn sau, nhưng người đọc phải hiểu được nó trước đã.

2. **Tích cực sử dụng phép ẩn dụ.** Hãy so sánh các hệ thống với nhà hàng,
   bưu điện, thư viện, nhà máy, dàn nhạc giao hưởng — bất cứ thứ gì giúp
   khái niệm trở nên dễ hiểu ngay lập tức. Phép ẩn dụ phải NHẤT QUÁN trong phạm vi một phần
   (đừng đang ví von với nhà hàng lại nhảy sang bệnh viện ở giữa chừng lời giải thích).

3. **Kể câu chuyện TẠI SAO.** Đừng chỉ ghi chép lại những gì đang tồn tại.
   Hãy giải thích tại sao các quyết định lại được đưa ra, những phương án thay thế nào đã được cân nhắc,
   và những sự đánh đổi nào đã được chấp nhận. "Chúng ta chọn đi theo hướng X bởi vì Y,
   mặc dù điều đó có nghĩa là sau này chúng ta sẽ khó làm Z một cách dễ dàng."

4. **Viết thật cuốn hút.** Sử dụng giọng văn trò chuyện tự nhiên, các câu hỏi tu từ,
   chút hài hước nhẹ nhàng ở những chỗ phù hợp. Tài liệu này phải là thứ mà
   người ta thực sự MUỐN đọc, chứ không phải thứ họ bị ép phải đọc.
   Nếu một phần nào đó terdengar nhàm chán, hãy viết lại cho đến khi nó hết chán.

5. **Trung thực về các vấn đề.** Hãy gắn cờ chỉ rõ các khoản nợ kỹ thuật, các sự cố đã biết,
   và những quyết định kiểu "chúng ta làm thế này vì áp lực thời gian". Tài liệu này
   sẽ hữu ích hơn nhiều khi nó chân thực thay vì cố tỏ ra bóng bẩy hoàn hảo.

6. **Bao gồm mục "chuyện gì có thể trục trặc" cho mọi hệ thống chính.**
   Không phải để hù dọa, mà là để chuẩn bị sẵn sàng. "Nếu dịch vụ thanh toán bị sập,
   đây là những gì sẽ xảy ra và đây là những gì cần làm."

7. **Sử dụng kỹ thuật hé lộ thông tin tăng dần (progressive disclosure).** Bắt đầu mỗi phần bằng
   phiên bản đơn giản trước, sau đó mới đi sâu hơn. Người đọc có thể dừng lại
   ở bất kỳ điểm nào mà vẫn nắm được một lượng kiến thức hữu ích.

8. **Định dạng để dễ đọc lướt (scannability).** Sử dụng các tiêu đề, in đậm các thuật ngữ quan trọng, chia đoạn văn
   ngắn và dùng gạch đầu dòng cho các danh sách. Nhưng hãy viết bằng văn xuôi (không dùng gạch đầu dòng)
   đối với các phần giải thích và dẫn chuyện.

## Ví dụ về Giọng văn

SAI — khô khan và nặng nề biệt ngữ:
"Ứng dụng triển khai kết xuất phía máy chủ (server-side rendering) với cơ chế tái tạo tĩnh
tăng dần (incremental static regeneration), tận dụng Next.js App Router cùng React Server
Components để đạt chỉ số TTFB tối ưu."

ĐÚNG — rõ ràng và lôi cuốn:
"Khi có ai đó truy cập trang web của chúng ta, máy chủ sẽ dựng sẵn trang đó trước khi
gửi đi — giống như một nhà hàng chuẩn bị sẵn món ăn trước khi bạn bước vào quán
thay vì đợi bạn ngồi xuống rồi mới bắt đầu nấu từ đầu. Kỹ thuật này được gọi là
'kết xuất phía máy chủ' ('server-side rendering') và đó là lý do tại sao các trang web tải rất nhanh. Chúng ta sử dụng Next.js
App Router cho việc này, nó giống như hệ thống điều phối quy trình làm việc của nhà bếp giúp
quyết định món nào cần sơ chế trước và món nào sẽ nấu ngay khi có khách gọi."

SAI — liệt kê trống không thiếu ngữ cảnh:
"Các gói phụ thuộc: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe"

ĐÚNG — giải thích như một đội ngũ nhân sự:
"Hãy hình dung ngăn xếp công nghệ (tech stack) của chúng ta như một đoàn làm phim, mỗi thành viên có một chuyên môn riêng:
- **React** là nhà thiết kế bối cảnh — nó dựng nên mọi thứ bạn nhìn thấy trên màn hình
- **Next.js** là quản lý sân khấu — nó điều phối thời điểm và cách thức mọi thứ xuất hiện
- **Tailwind** là bộ phận phục trang — nó phụ trách toàn bộ phần tạo kiểu hình ảnh
- **Supabase** là nhân viên lưu trữ hồ sơ — nó cất giữ và truy xuất toàn bộ dữ liệu của chúng ta
- **Stripe** là nhân viên thu ngân — nó xử lý mọi vấn đề liên quan đến tiền bạc một cách an toàn"

## 🚀 Dịch Vụ Rút Ngắn URL — Ứng Dụng Full-Stack

### 📋 Tổng Quan Dự Án
Xây dựng một dịch vụ rút ngắn URL full-stack sẵn sàng cho môi trường thực tế (production-ready) với giao diện người dùng hiện đại, dễ tiếp cận và hệ thống RESTful backend API mạnh mẽ. Ứng dụng phải xử lý trọn vẹn vòng đời của các liên kết rút gọn: khởi tạo, chuyển hướng, theo dõi, quản lý và hết hạn. Ưu tiên hiệu năng, tính bảo mật và trải nghiệm người dùng xuất sắc trên mọi thiết bị.

---

### 🛠️ Ngăn Xếp Công Nghệ (Tech Stack)

**Frontend:**
- HTML5 ngữ nghĩa kết hợp các thuộc tính ARIA nhằm đảm bảo khả năng tiếp cận (tuân thủ chuẩn WCAG 2.1 AA)
- CSS3 sử dụng CSS Custom Properties (biến CSS), Flexbox và CSS Grid
- Vanilla JavaScript (ES2022+) sử dụng kiến trúc mô-đun (ES Modules)
- Không dùng các framework nặng nề — giữ cho gói mã nguồn gọn nhẹ và tốc độ tải nhanh

**Backend API:**
- Thiết kế RESTful API tuân theo đặc tả OpenAPI 3.0
- Định dạng yêu cầu/phản hồi JSON đi kèm các mã trạng thái HTTP chuẩn xác
- Cấu hình CORS cho các yêu cầu liên nguồn (cross-origin requests)
- Giới hạn tần suất gửi yêu cầu (rate limiting) theo từng địa chỉ IP và theo từng API key

**Thư viện (qua CDN hoặc đóng gói kèm):**
- Tạo mã QR (ví dụ: `qrcode.js` hoặc `qr-creator`)
- Thư viện vẽ biểu đồ phục vụ phân tích (ví dụ: Chart.js hoặc giải pháp thay thế gọn nhẹ)
- Bộ chọn ngày tháng cho tính năng hết hạn liên kết (ví dụ: `flatpickr`)
- Hệ thống thông báo nổi (toast notification) (tự xây dựng, không dùng thư viện phụ thuộc)

---

### 🎨 Frontend — Yêu Cầu Giao Diện & Trải Nghiệm Người Dùng (UI/UX)

**Bố Cục & Thiết Kế:**
- Thiết kế tối giản, sạch sẽ với phần mở đầu (hero section) nổi bật bởi **ô nhập URL lớn, bắt mắt** nằm ngay chính giữa trang
- Triển khai **nút chuyển đổi chế độ tối/sáng (dark/light mode)** có khả năng tự nhận diện tùy chọn hệ thống (`prefers-color-scheme`) và lưu trạng thái vào `localStorage`
- Sử dụng hệ thống thiết kế nhất quán: thang tỷ lệ chữ (typography scale), các token khoảng cách, bảng màu chuẩn
- Các hiệu ứng chuyển cảnh và hoạt ảnh vi mô (micro-animations) mượt mà (hiện dần, trượt lên, gợn sóng trên nút bấm) cho mọi phần tử tương tác
- Trạng thái khung xương chờ tải (skeleton loading) cho các nội dung bất đồng bộ (bảng phân tích, bảng lịch sử)

**Thiết Kế Đáp Ứng (Responsive Design):**
- Tiếp cận theo hướng ưu tiên thiết bị di động (mobile-first) với các điểm ngắt (breakpoints) tại 480px, 768px, 1024px và 1440px
- Vùng chạm thân thiện với màn hình cảm ứng (kích thước tối thiểu 44×44px)
- Menu điều hướng có thể thu gọn trên thiết bị di động (menu hamburger kèm hiệu ứng chuyển động)
- Cỡ chữ linh hoạt sử dụng hàm `clamp()`

**Khả Năng Tiếp Cận (Accessibility):**
- Hỗ trợ điều hướng hoàn toàn bằng bàn phím (thứ tự phím Tab, giữ tiêu điểm focus bên trong cửa sổ modal)
- Thông báo qua trình đọc màn hình cho các nội dung thay đổi động (vùng `aria-live`)
- Đường viền chỉ báo tiêu điểm (focus indicators) hiển thị rõ ràng trên mọi phần tử tương tác
- Tỷ lệ tương phản màu sắc đạt chuẩn (tối thiểu 4.5:1 đối với văn bản)
- Hỗ trợ chế độ giảm chuyển động (`prefers-reduced-motion`)

---

### ⚙️ Các Tính Năng Cốt Lõi

#### 1. Bộ Máy Rút Ngắn URL
- Ô nhập liệu nổi bật có văn bản gợi ý (placeholder) và phản hồi kiểm tra tính hợp lệ theo thời gian thực
- **Kiểm tra tính hợp lệ của URL**: Kiểm tra giao thức hợp lệ (`http://`, `https://`), cấu trúc tên miền chuẩn xác, và từ chối các URL sai định dạng bằng cách kết hợp cả biểu thức chính quy (regex) lẫn API hàm tạo `URL`
- **Làm sạch URL (URL sanitization)**: Loại bỏ các tham số theo dõi (UTM, fbclid, gclid), xóa các dấu gạch chéo dư thừa, chuẩn hóa giao thức và chữ hoa/thường
- Tự động thêm tiền tố `https://` nếu người dùng không nhập giao thức
- Hiển thị ngay URL đã rút gọn sau khi tạo kèm theo hoạt ảnh báo thành công
- **Rút ngắn URL hàng loạt**: Cho phép người dùng dán nhiều URL cùng lúc (mỗi dòng một URL) và rút ngắn tất cả chỉ trong một lần thao tác

#### 2. Hỗ Trợ Bí Danh Tùy Chỉnh (Custom Alias)
- Trường nhập bí danh tùy chỉnh không bắt buộc (ví dụ: `short.ly/my-brand`)
- Kiểm tra tình trạng khả dụng theo thời gian thực ngay khi người dùng gõ phím (gọi API có debounce 300ms)
- Quy tắc kiểm tra bí danh: chỉ chấp nhận chữ cái, chữ số, dấu gạch ngang và dấu gạch dưới; độ dài từ 3–30 ký tự; danh sách đen chặn các từ khóa dành riêng cho hệ thống (ví dụ: `admin`, `api`, `login`, `static`)
- Thông báo lỗi rõ ràng nếu bí danh đã có người dùng hoặc không hợp lệ

#### 3. Tạo Mã QR
- Tự động tạo mã QR cho mọi URL rút gọn ngay khi khởi tạo xong
- Cửa sổ modal/khung điều khiển mã QR với các tùy chọn:
  - Tải xuống dưới định dạng PNG (độ phân giải cao, 1024×1024)
  - Tải xuống dưới định dạng SVG (đồ họa vector, phóng to không vỡ hình)
  - Tùy chỉnh màu sắc tiền cảnh/hậu cảnh
  - Chèn thêm lớp phủ logo nhỏ ở chính giữa (tùy chọn)
- Đảm bảo mã QR mã hóa đầy đủ URL rút gọn và có thể quét dễ dàng ngay cả ở kích thước nhỏ

#### 4. Theo Dõi Lượt Nhấp & Bảng Điều Khiển Phân Tích
- Ghi nhận mọi lượt chuyển hướng với các điểm dữ liệu sau:
  - Dấu thời gian (múi giờ UTC)
  - Quốc gia và thành phố (thông qua API định vị địa lý từ địa chỉ IP)
  - Loại thiết bị (điện thoại, máy tính bảng, máy tính để bàn)
  - Hệ điều hành và trình duyệt (thông qua phân tích chuỗi User-Agent)
  - URL nguồn giới thiệu (Referrer URL)
  - Khách truy cập duy nhất so với khách quay lại (thông qua cookie/fingerprint)
- **Bảng Điều Khiển Phân Tích** riêng cho từng liên kết bao gồm:
  - Bộ đếm tổng số lượt nhấp và số lượt nhấp duy nhất
  - Biểu đồ đường thể hiện số lượt nhấp theo thời gian (có bộ lọc: 24 giờ qua, 7 ngày, 30 ngày, 90 ngày, toàn thời gian)
  - Bản đồ phân bố địa lý hoặc biểu đồ cột ngang (10 quốc gia dẫn đầu)
  - Tỷ lệ phân bổ Thiết bị/Hệ điều hành/Trình duyệt (biểu đồ tròn hoặc biểu đồ vòng donut)
  - Bảng thống kê các nguồn giới thiệu (referrers) hàng đầu
  - Biểu đồ nhiệt (heatmap) lượt nhấp theo các ngày trong tuần và các giờ trong ngày
- Tổng quan phân tích gộp chung trên bảng điều khiển chính (tổng số liên kết, tổng số lượt nhấp, liên kết phổ biến nhất)

#### 5. Thời Hạn Liên Kết (Link Expiration)
- Bộ chọn ngày/giờ hết hạn không bắt buộc khi tạo liên kết
- Hỗ trợ các mốc cài đặt sẵn: 1 giờ, 24 giờ, 7 ngày, 30 ngày, hoặc chọn ngày tùy chỉnh
- Hiển thị đồng hồ đếm ngược hoặc huy hiệu "hết hạn sau X" trên các liên kết đang hoạt động
- Tự động vô hiệu hóa các liên kết đã quá hạn và hiển thị trang thông báo thân thiện "Liên kết này đã hết hạn" khi có người truy cập chuyển hướng
- Cho phép người dùng gia hạn thêm hoặc gỡ bỏ thời hạn trên các liên kết hiện có

#### 6. Bảo Vệ Bằng Mật Khẩu
- Nút bật/tắt mật khẩu không bắt buộc khi tạo liên kết
- Nếu được bật, hiển thị trang cổng nhập mật khẩu trước khi chuyển hướng tới URL đích
- Băm (hash) mật khẩu ở phía máy chủ bằng thuật toán bcrypt hoặc Argon2 (tuyệt đối không lưu mật khẩu dạng văn bản thuần)
- Giới hạn số lần thử mật khẩu (tối đa 5 lần mỗi phút trên mỗi IP) kèm thông báo khóa tạm thời
- Chỉ báo trực quan (biểu tượng ổ khóa 🔒) trên các liên kết được bảo vệ bằng mật khẩu trong danh sách lịch sử

#### 7. Sao Chép Vào Bộ Nhớ Tạm (Copy-to-Clipboard)
- Nút sao chép chỉ với một cú nhấp chuột nằm ngay cạnh mỗi URL rút gọn
- Sử dụng Clipboard API (`navigator.clipboard.writeText()`) kèm phương án dự phòng dùng `document.execCommand('copy')`
- Xác nhận trực quan: biểu tượng trên nút chuyển thành dấu tích ✅ cùng chú giải/thông báo nổi "Đã sao chép!" tự động biến mất sau 2 giây
- Hỗ trợ phím tắt bàn phím (ví dụ: nhấn `Ctrl+Shift+C` để sao chép liên kết vừa tạo gần nhất)

#### 8. Lịch Sử & Quản Lý URL
- Bảng/lưới lịch sử lưu trữ bền vững toàn bộ các URL đã rút gọn (lưu trong `localStorage` đối với khách vãng lai, lưu trong cơ sở dữ liệu đối với người dùng đã đăng nhập)
- Mỗi mục hiển thị: URL gốc (được cắt gọn kèm chú giải tooltip khi di chuột), URL rút gọn, ngày tạo, số lượt nhấp, trạng thái (đang hoạt động/đã hết hạn/có mật khẩu), và các nút thao tác
- **Tìm kiếm**: Tìm kiếm toàn văn trên URL gốc, bí danh và thẻ phân loại (tags)
- **Bộ lọc**: Lọc theo trạng thái (đang hoạt động, đã hết hạn, có bảo vệ), khoảng thời gian, khoảng số lượt nhấp, và thẻ phân loại
- **Sắp xếp**: Theo ngày tạo, số lượt nhấp, thứ tự bảng chữ cái (tăng dần/giảm dần)
- **Phân trang hoặc cuộn vô tận** đối với danh sách lịch sử lớn (25 mục mỗi trang)
- **Thao tác hàng loạt**: Chọn nhiều liên kết cùng lúc để xóa, vô hiệu hóa, hoặc xuất ra tệp CSV/JSON
- **Thẻ/Nhãn phân loại (Tags/Labels)**: Cho phép người dùng gắn các thẻ tùy chỉnh để sắp xếp liên kết (ví dụ: "marketing", "social", "campaign-q4")

---

### 🔒 Yêu Cầu Bảo Mật
- Làm sạch dữ liệu đầu vào ở cả phía máy khách và máy chủ để ngăn chặn tấn công XSS
- Bảo vệ chống tấn công CSRF trên tất cả các điểm cuối (endpoints) API có làm thay đổi trạng thái
- Kiểm tra tính hợp lệ và làm sạch địa chỉ đích chuyển hướng nhằm ngăn chặn lỗ hổng chuyển hướng mở (open redirect) (chỉ đưa các giao thức hợp lệ vào danh sách trắng, chặn các lược đồ `javascript:`, `data:`, `file:`)
- Triển khai các tiêu đề Content Security Policy (CSP)
- Giới hạn tần suất (Rate limiting): tối đa 20 lần tạo liên kết mỗi phút trên mỗi IP; tối đa 100 yêu cầu API mỗi phút
- Các tiêu đề HTTP bảo mật: `X-Content-Type-Options`, `X-Frame-Options`, `Strict-Transport-Security`
- Tuyệt đối không để lộ ID nội bộ; sử dụng nanoid hoặc UUID làm mã định danh liên kết công khai

---

### ⚡ Yêu Cầu Hiệu Năng
- Điểm số Lighthouse mục tiêu: Performance >90, Accessibility >95, Best Practices >95, SEO >90
- Tải trễ (lazy-load) các biểu đồ phân tích và những tài nguyên không thiết yếu
- Thực hiện debounce cho toàn bộ các ô nhập liệu tìm kiếm và kiểm tra tính hợp lệ
- Sử dụng `IntersectionObserver` cho các hoạt ảnh kích hoạt theo thao tác cuộn trang và tải trễ (lazy loading)
- Giảm thiểu tối đa việc tính toán lại bố cục (reflows) và vẽ lại (repaints); sử dụng thuộc tính CSS `transform` và `opacity` cho các hiệu ứng chuyển động
- Lưu bộ nhớ đệm (cache) các phản hồi API ở những nơi phù hợp (ví dụ: dữ liệu phân tích với thời gian sống TTL là 60 giây)
- Các thao tác chuyển hướng phải được xử lý xong trong vòng chưa đầy 100ms ở phía máy chủ

---

### 🧪 Xử Lý Lỗi & Các Trường Hợp Biên (Edge Cases)
- Hiển thị thông báo lỗi thân thiện, mượt mà đối với các trường hợp: mất kết nối mạng, hết thời gian chờ phản hồi API (timeouts), URL không hợp lệ, trùng lặp bí danh, lỗi máy chủ (500), vượt quá giới hạn tần suất yêu cầu (429)
- Phát hiện trạng thái ngoại tuyến (offline): hiển thị thanh thông báo khi người dùng mất kết nối mạng và đưa các thao tác vào hàng đợi để thử lại sau
- Xử lý tốt các URL cực dài (lên tới 2048 ký tự) mà không làm vỡ bố cục giao diện
- Xử lý chính xác các tên miền quốc tế hóa/chứa ký tự Unicode (IDN)
- Có hình minh họa trạng thái trống (empty state) khi người dùng chưa có liên kết nào hoặc chưa có dữ liệu phân tích

---

### 📁 Sản Phẩm Bàn Giao (Deliverables)
1. Mã nguồn hoàn chỉnh, có chú thích rõ ràng cùng cấu trúc thư mục mạch lạc
2. Tệp `README.md` kèm hướng dẫn cài đặt, tài liệu API và danh sách tính năng
3. Bảng tra cứu các điểm cuối API (phương thức, đường dẫn, tham số, định dạng phản hồi)
4. Chế độ `demo` được nạp sẵn dữ liệu mẫu để có thể xem trước ngay lập tức
5. Hiển thị đáp ứng tốt trên các trình duyệt Chrome, Firefox, Safari và Edge (2 phiên bản mới nhất)

---

> **Lưu ý:** Hãy xây dựng ứng dụng này theo từng bước tăng dần — bắt đầu với luồng rút ngắn cốt lõi (nhập liệu → kiểm tra hợp lệ → rút ngắn → hiển thị → sao chép), sau đó mới bổ sung dần các lớp tính năng mã QR, phân tích, bí danh tùy chỉnh, thời hạn liên kết, bảo vệ bằng mật khẩu và bảng điều khiển lịch sử đầy đủ. Đảm bảo mỗi tính năng đều hoạt động hoàn chỉnh và được kiểm thử kỹ trước khi chuyển sang tính năng tiếp theo.

---
name: accessibility-color-contrast-auditor
description: Kiểm toán các cặp màu tiền cảnh/hậu cảnh theo độ tương phản WCAG 2.x (mức AA và AAA cho văn bản thường và văn bản lớn), báo cáo tỷ lệ và kết quả đạt/không đạt, đồng thời lưu ý các rủi ro đối với người mù màu. Sử dụng khi kiểm tra bảng màu giao diện người dùng (UI palette), design token, hoặc hỏi "màu xám trên nền trắng này có dễ đọc không?". Bao gồm công cụ kiểm tra độ tương phản bằng thư viện chuẩn Python có hỗ trợ --self-test.
---

# Công cụ Kiểm toán Độ tương phản Màu sắc cho Khả năng Tiếp cận

Bạn giúp các nhà thiết kế và kỹ sư frontend kiểm tra xem màu sắc của văn bản và giao diện người dùng (UI) có đáp ứng tỷ lệ tương phản WCAG 2.x hay không. Bạn tính toán độ tương phản độ chói tương đối (relative luminance contrast) cho các cặp màu tiền cảnh/hậu cảnh, đối chiếu kết quả với tiêu chuẩn AA/AAA cho văn bản thường và văn bản lớn, đồng thời gắn cờ cảnh báo các cặp màu chỉ dựa vào sắc độ (hue) để truyền tải ý nghĩa.

## Các tệp trong kỹ năng này

- `scripts/contrast_check.py` - tính toán tỷ lệ tương phản cho các cặp mã màu hex và in ra bảng kết quả đạt/không đạt (chỉ dùng thư viện chuẩn Python 3)
- `references/wcag-contrast.md` - các ngưỡng tiêu chuẩn và quy định thế nào được tính là văn bản lớn
- `references/color-blindness-notes.md` - lý do tại sao các màu trạng thái chỉ phân biệt bằng sắc độ lại gây lỗi với người dùng thực tế
- `templates/audit-table.md` - bảng markdown phục vụ đánh giá thiết kế
- `examples/palette.json` - các cặp token mẫu

## Quy trình làm việc

### 1. Thu thập các cặp màu
Yêu cầu cung cấp các mã màu hex (`#RGB`, `#RRGGBB`, hoặc `#RRGGBBAA` với kênh alpha được bỏ qua trên nền đục). Ghi chú rõ màu nào là văn bản/biểu tượng (fg) và màu nào là bề mặt nền (bg).

### 2. Chạy công cụ kiểm tra
```
python3 scripts/contrast_check.py --fg '#1a1a1a' --bg '#ffffff'
python3 scripts/contrast_check.py --palette examples/palette.json
python3 scripts/contrast_check.py --self-test
```

### 3. Diễn giải kết quả
- Văn bản thường mức AA cần **4.5:1**; mức AAA cần **7:1**.
- Văn bản lớn (18pt+ hoặc 14pt+ in đậm) mức AA cần **3:1**; mức AAA cần **4.5:1**.
- Các thành phần giao diện người dùng phi văn bản / đối tượng đồ họa mang ý nghĩa cần đạt **3:1** so với các màu liền kề (WCAG 2.1 SC 1.4.11).

### 4. Trả lời
Đối với mỗi cặp màu: nêu tỷ lệ (làm tròn một chữ số thập phân), kết quả AA/AAA cho văn bản thường, AA/AAA cho văn bản lớn, và gợi ý khắc phục ngắn gọn (làm tối màu fg, làm sáng màu bg, hoặc tăng độ đậm/kích thước chữ). Nhắc đến vấn đề mù màu nếu trạng thái chỉ phụ thuộc vào sự khác biệt giữa màu đỏ và màu xanh lá.

## Quy tắc

- Sử dụng công thức độ chói tương đối của WCAG; không ước lượng cảm tính bằng mắt thường ("eyeballing").
- Bỏ qua các tuyên bố tiếp thị về "chế độ hỗ trợ tiếp cận" trừ khi có hiển thị tỷ lệ tương phản cụ thể.
- Nếu có pha trộn kênh alpha (alpha blending), hãy yêu cầu mã màu hex thực tế sau khi đã làm phẳng trên nền thật.
FILE:references/wcag-contrast.md
# Các ngưỡng tương phản WCAG (WCAG 2.1 / 2.2)

| Nội dung | AA | AAA |
| --- | --- | --- |
| Văn bản thường | 4.5:1 | 7:1 |
| Văn bản lớn | 3:1 | 4.5:1 |
| Thành phần UI & đối tượng đồ họa (1.4.11) | 3:1 | — |

## Văn bản lớn

Văn bản lớn là văn bản có kích thước tối thiểu **18 CSS pt** (thường là 24px) đối với chữ thường, hoặc **14 CSS pt** (thường là 18.66px) đối với chữ in đậm.

## Độ chói tương đối (Relative luminance)

Đối với kênh màu sRGB C_srgb trong khoảng 0..1:

- nếu C_srgb <= 0.04045: C = C_srgb / 12.92
- ngược lại: C = ((C_srgb + 0.055) / 1.055) ^ 2.4

L = 0.2126 R + 0.7152 G + 0.0722 B

Tỷ lệ tương phản = (L_lighter + 0.05) / (L_darker + 0.05)

## Ghi chú

- Văn bản giữ chỗ (placeholder) / văn bản bị vô hiệu hóa (disabled) được miễn trừ khỏi các tiêu chí thành công (SC) về độ tương phản văn bản nhưng vẫn nên đảm bảo sự rõ ràng.
- Các chỉ báo tiêu điểm (focus indicators) cần đạt tỷ lệ 3:1 so với các màu liền kề (2.4.11 / 2.4.13 tùy theo cấp độ).
FILE:references/color-blindness-notes.md
# Ghi chú về chứng mù màu đối với bảng màu

Chỉ riêng tỷ lệ tương phản là không đủ khi ý nghĩa chỉ được truyền tải thông qua sắc độ (hue).

## Các lỗi thường gặp

- **Trạng thái đỏ so với xanh lá** không kèm biểu tượng hoặc nhãn văn bản: người mắc chứng mù màu lục/đỏ (deuteranomaly/protanomaly) có thể không phân biệt được chúng.
- **Các chuỗi dữ liệu biểu đồ** chỉ phân biệt bằng màu sắc: hãy thêm họa tiết, hình dạng, hoặc nhãn trực tiếp.
- **Màu liên kết (link)** có cùng độ sáng với văn bản thân bài: đường gạch chân hoặc độ đậm của chữ phải được giữ nguyên khi loại bỏ yếu tố màu sắc.
- **Viền báo lỗi** chỉ có sắc đỏ nhạt: hãy đảm bảo tỷ lệ 3:1 so với màu nền và kèm theo văn bản/biểu tượng.

## Các mẫu thiết kế an toàn hơn

1. Kết hợp màu sắc với văn bản ("Error", "Success") hoặc biểu tượng.
2. Sử dụng sự chênh lệch về độ sáng (lightness), chứ không chỉ dịch chuyển sắc độ (hue).
3. Kiểm tra bằng ảnh chụp màn hình giao diện ở chế độ thang độ xám (grayscale).
4. Tránh chỉ dùng mỗi màu đỏ để biểu thị trạng thái trường bắt buộc nhập.

## Mẹo thân thiện với người mắc chứng mù màu lục (Deuteranopia)

Ưu tiên sử dụng các cặp màu xanh dương/cam hoặc xanh dương/nâu thay vì đỏ/xanh lá cho dữ liệu phân loại khi bạn bắt buộc phải dùng hai sắc độ.
FILE:templates/audit-table.md
# Kiểm toán độ tương phản

- **Sản phẩm / màn hình**:
- **Ngày**:
- **Tiêu chuẩn**: WCAG 2.2 AA (mặc định) / AAA ở những nơi được ghi chú

| Token / mục đích sử dụng | FG | BG | Tỷ lệ | AA thường | AAA thường | AA lớn | Ghi chú / cách sửa |
| --- | --- | --- | --- | --- | --- | --- | --- |
| văn bản thân bài | `#1a1a1a` | `#ffffff` | 16.1 | pass | pass | pass | |
| chú thích mờ | `#9ca3af` | `#ffffff` | 2.5 | fail | fail | fail | Làm tối xuống khoảng ~`#6b7280` |

## Quyết định

- [ ] Cập nhật các token
- [ ] Chấp nhận chỉ sử dụng cho văn bản lớn
- [ ] Thêm dấu hiệu nhận biết phi màu sắc
FILE:examples/palette.json
{
  "pairs": [
    {"name": "body_on_white", "fg": "#1a1a1a", "bg": "#ffffff"},
    {"name": "muted_on_white", "fg": "#9ca3af", "bg": "#ffffff"},
    {"name": "link_on_white", "fg": "#2563eb", "bg": "#ffffff"},
    {"name": "button_label", "fg": "#ffffff", "bg": "#2563eb"},
    {"name": "error_on_white", "fg": "#dc2626", "bg": "#ffffff"},
    {"name": "white_on_light_gray", "fg": "#ffffff", "bg": "#e5e7eb"}
  ]
}
FILE:scripts/contrast_check.py
#!/usr/bin/env python3
"""WCAG contrast ratio checker for hex fg/bg pairs.

Usage:
    python3 contrast_check.py --fg '#1a1a1a' --bg '#ffffff'
    python3 contrast_check.py --palette palette.json
    python3 contrast_check.py --self-test

Python 3 standard library only.
"""
from __future__ import annotations

import argparse
import json
import math
import sys
from typing import Dict, List, Tuple


def parse_hex(color: str) -> Tuple[float, float, float]:
    c = color.strip().lstrip("#")
    if len(c) == 3:
        c = "".join(ch * 2 for ch in c)
    if len(c) == 8:
        c = c[:6]  # ignore alpha
    if len(c) != 6:
        raise ValueError(f"Bad hex color: {color!r}")
    r = int(c[0:2], 16) / 255.0
    g = int(c[2:4], 16) / 255.0
    b = int(c[4:6], 16) / 255.0
    return r, g, b


def channel(c: float) -> float:
    if c <= 0.04045:
        return c / 12.92
    return ((c + 0.055) / 1.055) ** 2.4


def relative_luminance(rgb: Tuple[float, float, float]) -> float:
    r, g, b = rgb
    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)


def contrast_ratio(fg: str, bg: str) -> float:
    l1 = relative_luminance(parse_hex(fg))
    l2 = relative_luminance(parse_hex(bg))
    lighter, darker = max(l1, l2), min(l1, l2)
    return (lighter + 0.05) / (darker + 0.05)


def evaluate(ratio: float) -> Dict[str, bool]:
    return {
        "aa_normal": ratio >= 4.5,
        "aaa_normal": ratio >= 7.0,
        "aa_large": ratio >= 3.0,
        "aaa_large": ratio >= 4.5,
        "ui_3_1": ratio >= 3.0,
    }


def format_row(name: str, fg: str, bg: str) -> str:
    ratio = contrast_ratio(fg, bg)
    ev = evaluate(ratio)
    flags = " ".join(
        f"{k}={'PASS' if v else 'FAIL'}"
        for k, v in ev.items()
        if k in ("aa_normal", "aaa_normal", "aa_large")
    )
    return f"{name}: {fg} on {bg} -> {ratio:.2f}:1  {flags}"


def self_test() -> int:
    cases = [
        ("black_white", contrast_ratio("#000000", "#ffffff"), 21.0),
        ("white_black", contrast_ratio("#ffffff", "#000000"), 21.0),
        ("body", contrast_ratio("#1a1a1a", "#ffffff") > 12.0, True),
        ("muted_fail_aa", evaluate(contrast_ratio("#9ca3af", "#ffffff"))["aa_normal"], False),
        ("link_aa", evaluate(contrast_ratio("#2563eb", "#ffffff"))["aa_normal"], True),
        ("same_color", abs(contrast_ratio("#ffffff", "#ffffff") - 1.0) < 1e-9, True),
        ("short_hex", abs(contrast_ratio("#000", "#fff") - 21.0) < 1e-9, True),
        ("parse3", parse_hex("#abc") == parse_hex("#aabbcc"), True),
        ("ui_pass", evaluate(3.0)["ui_3_1"], True),
        ("aaa_border", evaluate(7.0)["aaa_normal"], True),
        ("just_under_aa", evaluate(4.49)["aa_normal"], False),
    ]
    failed = 0
    for name, got, expected in cases:
        if isinstance(expected, float):
            ok = abs(float(got) - expected) < 0.05
        else:
            ok = got == expected
        failed += not ok
        print(f"{'PASS' if ok else 'FAIL'}  {name}: got={got!r} expected={expected!r}")
    print(f"\n{len(cases) - failed}/{len(cases)} passed")
    return 1 if failed else 0


def main(argv=None) -> int:
    p = argparse.ArgumentParser(description="Check WCAG contrast for fg/bg hex pairs.")
    p.add_argument("--fg")
    p.add_argument("--bg")
    p.add_argument("--palette", help="JSON file with {pairs:[{name,fg,bg}]}")
    p.add_argument("--json", action="store_true")
    p.add_argument("--self-test", action="store_true")
    a = p.parse_args(argv)
    if a.self_test:
        return self_test()
    rows = []
    if a.palette:
        data = json.load(open(a.palette, encoding="utf-8"))
        for pair in data.get("pairs", []):
            rows.append(pair)
    elif a.fg and a.bg:
        rows.append({"name": "pair", "fg": a.fg, "bg": a.bg})
    else:
        p.error("provide --fg and --bg, or --palette, or --self-test")
    out = []
    any_fail = False
    for row in rows:
        ratio = contrast_ratio(row["fg"], row["bg"])
        ev = evaluate(ratio)
        if not ev["aa_normal"]:
            any_fail = True
        item = {"name": row.get("name", "pair"), "fg": row["fg"], "bg": row["bg"], "ratio": round(ratio, 2), **ev}
        out.append(item)
        if not a.json:
            print(format_row(item["name"], item["fg"], item["bg"]))
    if a.json:
        print(json.dumps(out, indent=2))
    return 1 if any_fail else 0


if __name__ == "__main__":
    sys.exit(main())

# Phong cách (taste) CSS của một lập trình viên frontend có tư duy thiết kế
- Sử dụng các lớp tiện ích (utility classes) của Tailwind CSS để định kiểu cho component trong mã nguồn ứng dụng. Độ tin cậy: 0.80
- Định nghĩa màu sắc, khoảng cách (spacing), độ bo góc (radii) và phông chữ dưới dạng các design token trong thuộc tính tùy chỉnh CSS (CSS custom properties). Độ tin cậy: 0.90
- Không bao giờ gán cứng (hardcode) mã màu hex bên trong các component; luôn tham chiếu đến một token. Độ tin cậy: 0.85
- Xây dựng bố cục bằng flexbox và grid, sử dụng thuộc tính gap để tạo khoảng cách thay vì dùng margin giữa các phần tử anh em (siblings). Độ tin cậy: 0.90
- Thiết kế ưu tiên thiết bị di động (mobile first) và thêm các điểm ngắt (breakpoints) min-width cho màn hình lớn hơn. Độ tin cậy: 0.85
- Sử dụng container queries cho các component nằm trong những vùng chứa có chiều rộng khác nhau. Độ tin cậy: 0.75
- Sử dụng đơn vị rem cho kích thước phông chữ và khoảng cách, và chỉ dùng px cho đường viền mảnh (hairline borders). Độ tin cậy: 0.80
- Sử dụng hàm clamp() cho kiểu chữ linh hoạt (fluid typography) thay vì ghi đè tại nhiều điểm ngắt. Độ tin cậy: 0.75
- Giữ độ ưu tiên (specificity) phẳng: bộ chọn một lớp duy nhất, không dùng ID và không dùng !important bên ngoài các lớp tiện ích. Độ tin cậy: 0.90
- Sử dụng cascade layers để sắp xếp thứ tự cho reset, base, components và utilities. Độ tin cậy: 0.70
- Hỗ trợ chế độ tối (dark mode) bằng prefers-color-scheme kết hợp với các token, thay vì nhân bản các kiểu dáng của component. Độ tin cậy: 0.85
- Tôn trọng prefers-reduced-motion và tắt các hiệu ứng chuyển động không cần thiết khi tùy chọn này được bật. Độ tin cậy: 0.90
- Không bao giờ xóa đường viền tiêu điểm (focus outlines); thay vào đó hãy định kiểu cho chúng bằng :focus-visible. Độ tin cậy: 0.95
- Đạt chuẩn độ tương phản WCAG AA cho tất cả văn bản và các phần tử tương tác. Độ tin cậy: 0.90
- Chỉ tạo hiệu ứng chuyển động (animate) trên thuộc tính transform và opacity để có các chuyển cảnh mượt mà và ít tốn tài nguyên. Độ tin cậy: 0.85
- Sử dụng các thuộc tính logic như margin-inline để bố cục hoạt động tốt với cả các ngôn ngữ viết từ phải sang trái (RTL). Độ tin cậy: 0.75
- Sử dụng bộ phông chữ hệ thống (system font stack) hoặc phông chữ biến thiên (variable fonts) tự lưu trữ với thuộc tính font-display: swap. Độ tin cậy: 0.80
- Đặt thuộc tính aspect-ratio cùng với width và height trên các phần tử đa phương tiện (media) để ngăn chặn hiện tượng dịch chuyển bố cục (layout shift). Độ tin cậy: 0.85
- Sử dụng tính năng lồng nhau (nesting) nguyên bản của CSS một cách tiết chế và không bao giờ vượt quá hai cấp độ. Độ tin cậy: 0.70
- Tự động sắp xếp các lớp Tailwind bằng plugin Prettier. Độ tin cậy: 0.80
- Tách thành một component riêng khi cùng một danh sách dài các lớp lặp đi lặp lại, thay vì tạo lớp bằng @apply. Độ tin cậy: 0.75
- Đảm bảo không có phần tử nào bị cuộn ngang ở chiều rộng khung nhìn (viewport) 320px. Độ tin cậy: 0.85