IQ Kids Pixel UI

React 19, TypeScript và Tailwind CSS v4 cho giao diện học tập gamification phong cách Pixel Art 16-bit.

Tài liệu chính

• AGENTS.md — quy tắc và hướng dẫn sử dụng thư viện dành cho AI Agent.
• WORKFLOW.md — kiến trúc, luồng phát triển và quy tắc UI.
• ASSET_GUIDE.md — thư viện asset, manifest và registry.

AI Agent Support

Package này tích hợp sẵn quy tắc cho AI Agent tại file AGENTS.md.

Tự động thiết lập quy tắc cho AI Agent trong dự án tiêu dùng:

Chạy lệnh sau trong dự án bất kỳ đã cài đặt package để cài đặt quy tắc vào .agents/rules/iqkids-ui.md:

npx @ngochoinct/ui-builder init-agent
# hoặc
npx iqkids-ui init-agent

Các AI Agent (Antigravity, Cursor, Windsurf, Claude Code, Copilot) sẽ tự động nhận diện và áp dụng quy tắc:

• Ưu tiên Mascot (<Mascot />): Bắt buộc dùng <Mascot /> cho mọi biểu cảm và trạng thái nhân vật, tuyệt đối không dùng Emoji.
• Ưu tiên PixelIcon (<PixelIcon />): Sử dụng PixelIcon chính thức cho biểu tượng UI, chỉ số, phần thưởng.
• Dùng background WebP: Sử dụng background WebP trong thư viện, không thay thế bằng màu CSS thuần.
• Thứ tự ưu tiên asset: Mascot → PixelIcon → Background → Existing Asset → New Asset.

Cài đặt & Sử dụng

npm install @ngochoinct/ui-builder

Sử dụng React Components:

import { Mascot, PixelIcon, PixelBackground, AssetProvider } from "@ngochoinct/ui-builder/react";

function App() {
  return (
    <AssetProvider baseUrl="/assets">
      <PixelBackground name="bg-01-skyday" style={{ minHeight: "100vh" }}>
        <div className="p-8">
          <Mascot pose="cheer" size={96} />
          <PixelIcon name="coin-gold" size={32} />
        </div>
      </PixelBackground>
    </AssetProvider>
  );
}

Import trực tiếp Asset từ Package:

import bgSky from "@ngochoinct/ui-builder/assets/backgrounds/bg-01-skyday.webp";
import cheerMascot from "@ngochoinct/ui-builder/assets/mascot/cheer.webp";
import coinIcon from "@ngochoinct/ui-builder/assets/icons/coin-gold.webp";

Chạy dự án (Development)

Cấu trúc mã nguồn

manifest/        # Metadata cho từng nhóm asset
source/          # PNG gốc, không chỉnh sửa
src/assets/      # WebP dùng khi build
src/lib/assets.ts # Registry TypeScript duy nhất
src/components/  # Thành phần UI/HUD dùng lại
src/features/    # Thành phần và nghiệp vụ theo feature
src/styles/      # CSS toàn cục và design tokens