AgentSkillsCN

Frontend Design

前端设计系统与模态框规范指南

SKILL.md
--- frontmatter
description: Frontend design system and modal guidelines
category: Implementation
boundary: Frontend (fe/)
version: 2.2

Frontend Design System

Visual patterns and UI conventions for fe/ components.

Tech Stack

  • •React SPA (Vite)
  • •Tailwind CSS + dark: variants
  • •SuperTokens (auth)
  • •TanStack Query (server state)
  • •Redux (global UI state)
  • •Lucide React (icons)

Design Philosophy

  • •Rounded, soft surfaces with subtle shadows (rounded-xl/2xl, shadow-md/2xl)
  • •Clear hierarchy: bold titles, muted supporting text, roomy spacing
  • •Primary actions are indigo; destructive actions are red
  • •Minimal borders, light separators, and consistent padding
  • •Use font-sans and consistent text sizes across screens

Dark Mode

Class-based dark mode via ThemeToggle → dark class on <html>.

Rule: All components must use dark:* counterparts for every color.

Color System

Surfaces

ElementLightDark
App canvasbg-gray-50bg-gray-950
Cards/modalsbg-whitebg-slate-900
Texttext-gray-900text-gray-50
Muted texttext-gray-500text-gray-400
Bordersborder-gray-200border-slate-700

Semantic Colors

PurposeLightDark
Primaryindigo-600indigo-500
Primary hoverindigo-700indigo-400
Info/loadingblue-*blue-*
Dangerred-*red-*

Layout Rules

  • •Pages are thin: page/* composes feature components
  • •Spacing: Use Tailwind scale (p-4, gap-2, space-y-6)
  • •Rounded: Prefer rounded-xl / rounded-2xl
  • •Max widths: Modals use max-w-* sizes (default max-w-lg)
  • •Panels: Use bg-white + dark:bg-slate-900 and border-gray-100 + dark:border-slate-800

Component Structure

core-design/ (Reusable)

Generic UI blocks without feature knowledge:

  • •Inputs: CommonInput, CommonButton, Select
  • •Modals: ModalBase, ConfirmModal
  • •Cards: ActiveMenu

Rules:

  • •No feature-specific data fetching
  • •No feature-specific Redux slices
  • •Props are generic and typed

components/<feature>/ (Feature Modules)

UI + behavior for a domain:

code
components/<feature>/
├── components/    # Pure subcomponents
├── hooks/         # Feature hooks
├── utils.ts       # Feature utilities
├── types.ts       # Feature types
└── store.ts       # Zustand store

Service Layer

code
services/<module>/
├── api.ts       # Low-level fetch calls
└── useQuery.ts  # TanStack Query hooks

Rule: UI components never call fetch directly—use hooks from useQuery.ts.

Modal System

Use ModalBase + useModal for all dialogs:

  • •Open/close via useModal (backed by store/modal.store.ts)
  • •Stacked modals are supported; top layer handles ESC
  • •Backdrop click closes unless blocked by custom logic
  • •Use ConfirmModal or WarningModal for destructive actions
  • •Use maxWidthClass to size modals (e.g., max-w-sm, max-w-lg)

Modal attributes for testing:

  • •data-modal, data-modal-panel, data-modal-confirm, data-modal-close

Form Controls

  • •Use CommonInput for text fields (floating labels supported)
  • •Use CurrencyInput for money and numeric inputs
  • •Use Select / SelectSearch for dropdowns
  • •Use CommonButton for primary actions (supports loading)

Forms & Validation

  • •Use react-hook-form for form state and submission
  • •Prefer zod schemas with zodResolver for validation
  • •Keep form schema in the same feature folder (e.g., components/<feature>/schema.ts)
  • •Map server errors to field errors when possible

Loading & Empty States

  • •Use Spinner for inline loading
  • •Prefer skeletons (ProductCardSkeleton, CategoryListSkeleton) for list screens
  • •Disable submit buttons while loading

Naming Conventions

  • •Components: PascalCase.tsx
  • •Hooks: useXxx.ts
  • •Utilities: utils.ts

Checklist (Before Merge)

  • • Works in both light and dark mode
  • • Uses consistent text colors (gray/slate)
  • • Interactive elements have hover states
  • • API logic in services/, primitives in core-design/