@ogg/admin

Mẫu quản trị React hiện đại để bán và triển khai dashboard.

Giao diện cobalt trên nền sáng, chế độ tối đầy đủ, Radix primitives bên dưới, và ứng dụng demo hoàn chỉnh (đăng nhập, 404, bảng, biểu mẫu, cài đặt…).

Bắt đầu nhanh

npm install
npm run dev

Mở http://localhost:5173.

Nội dung bao gồm

Trang demo

• Tổng quan
• Thư viện thành phần
• Bảng
• Biểu mẫu
• Hồ sơ
• Cài đặt (giao diện + thông báo)
• Đăng nhập / Đăng ký
• 404 / 500

Thành phần

Button, Card, Input, Textarea, Select, Checkbox, Switch, Badge, Avatar, Image, Modal, Drawer, Table, Tabs, Alert, Toast, Dropdown, Pagination, Breadcrumb, Spinner, Skeleton

Layout

AppShell, Sidebar, Topbar, Bảng lệnh (⌘K / Ctrl+K)

Công nghệ

• React 19 + TypeScript + Vite
• Radix UI primitives (nền tảng truy cập tốt)
• Design token tùy chỉnh (OKLCH) — chủ đề Cobalt sáng + chế độ tối
• Space Grotesk / Inter / JetBrains Mono
• React Router
• Lucide icons

Giao diện

Giao diện được điều khiển bởi data-theme="light|dark" trên <html> qua ThemeProvider.

import { ThemeProvider, useTheme } from '@ogg/admin'

function Toggle() {
  const { theme, toggleTheme } = useTheme()
  return <button onClick={toggleTheme}>{theme}</button>
}

Dùng như thư viện

npm run build:lib

Người dùng:

import { Button, Card, AppShell } from '@ogg/admin'
import '@ogg/admin/styles.css'

Bán / giấy phép

Gói này mặc định đánh dấu UNLICENSED. Trước khi đăng lên marketplace:

1. Đổi thương hiệu (Ogg Admin, logo, tên gói nếu cần)
2. Thêm file giấy phép thương mại
3. Quyết định người mua nhận toàn bộ mã nguồn (khuyến nghị cho template) và/hoặc quyền npm
4. Cung cấp README, ảnh xem trước và URL demo trực tiếp

Scripts

| Script | Mô tả | | --- | --- | | npm run dev | Ứng dụng demo | | npm run build | Build demo ra dist-demo | | npm run build:lib | Build thư viện xuất bản ra dist | | npm run preview | Xem trước bản build demo |

Cấu trúc dự án

src/
  components/   # Bộ UI
  layout/       # Khung app + ⌘K
  lib/          # cn(), paths
  pages/        # Màn demo
  router/       # AppRouter (React Router)
  styles/       # Token + CSS thành phần
  theme/        # Provider sáng/tối
  index.ts      # Entry gói

Dùng với AI (Cursor, Copilot, …)

Gói kèm tài liệu để AI đọc và dựng UI đúng design system:

| File | Mục đích | | --- | --- | | AGENTS.md | Hướng dẫn bắt buộc cho agent | | llms.txt | Bản đồ ngắn cho LLM | | docs/AI_GUIDE.md | Cách dùng component / theme / layout | | docs/ROUTES.md | Bảng route + cách thêm trang | | .cursor/rules/ogg-admin.mdc | Cursor project rules |

Mở project trong Cursor: agent sẽ nhận rules từ .cursor/rules/ và AGENTS.md. Khi cần thêm trang, cập nhật src/lib/paths.ts + src/router/index.tsx (xem docs/ROUTES.md).