MuAPI Client Design System

This document outlines the design standards and architectural patterns for the muapi client to ensure a consistent, "premium" aesthetic for all future development.

🎨 Design Tokens (CSS Variables)

Always use these standardized tokens in globals.css when implementing new UI:

Category	Token	Value	Use Case
Colors	--brand-primary	#3B82F6 (Blue-500)	Primary actions, links
	--brand-accent	#8B5CF6 (Violet-500)	Secondary accents, highlights
Backgrounds	--bg-page	#F8FAFC	Main page background
	--bg-card	#FFFFFF	Component containers
Text	--text-primary	#0F172A	Headings and body text
	--text-muted	#94A3B8	Hints, secondary labels
Borders	--border-subtle	#E2E8F0	Default card/list borders
Shadows	--shadow-card	0 1px 3px rgba(0,0,0,0.06)	Default lifting

📐 Layout & Spacing

Container Standards

• Width: Use max-w-7xl with responsive side padding: px-4 sm:px-8 lg:px-12.
• Top Spacing: pt-6 sm:pt-8 below the Navbar.
• Section Gaps: gap-6 sm:gap-8 for vertical spacing between sections.

Mobile-First Responsive Pattern

All pages follow the mobile-first responsive container:

<div className="... px-4 sm:px-8 lg:px-12">
  <div className="... w-full max-w-7xl">

• Never use fixed % widths like max-w-[90%] — use padding-based spacing instead.
• Stat grids: grid-cols-2 md:grid-cols-2 lg:grid-cols-4 (2×2 on mobile).
• Tables: Always wrap in overflow-x-auto with min-w-[500px] or min-w-[640px].
• Pagination: Use flex-col sm:flex-row for stacking on small screens.

Component Alignment

• Gaps: Standardize on gap-6 or gap-8 for vertical sections.
• Grouping: Use gap-2 for labels and their descriptions; gap-4 for form fields.

🧱 Premium Components

.card-premium

The foundational container for all data-driven modules.

• Spec: border border-slate-200, rounded-xl, shadow-sm, padding: 1.5rem.
• Responsive: Override padding on mobile with !p-4 sm:!p-6 when needed.
• Hover: Use .card-lift for interactive cards (-translate-y-0.5).

.btn-primary

Standard action button with gradient and hover animation.

• Always use for primary CTAs (Buy, Submit, Search).

.table-premium

Used for all history and usage log tables.

• Header: sticky, uppercase, tracking-widest.
• Rows: hover:bg-blue-50/40 with staggered animate-fade-in animations.
• Scrolling: Always wrap in overflow-x-auto container. Set min-w-[500px] on table.
• Empty State: Use centered icon + italic text at py-16 with opacity-40.

.stat-card

Dashboard metric cards with icon, label, and value.

• Grid: grid-cols-2 lg:grid-cols-4 for responsive layout.

Status Badges

Consistent badge styling for task states:

• Completed: .badge-success (Green)
• Processing: .badge-info (Blue)
• Failed: .badge-error (Red)

Tab Bar Pattern

Segmented toggle for tab navigation (e.g., Top Up / Billing):

<div className="flex items-center gap-1 bg-slate-100 p-1 rounded-xl border border-slate-200 max-w-xs">
  <button className={active ? "bg-white text-slate-900 shadow-sm" : "text-slate-500"}>

Pagination Pattern

Standardized pagination with pill-style container:

<div className="flex items-center bg-slate-100 p-1 rounded-lg border border-slate-200">
  <button>←</button>
  <input className="w-8 text-center font-bold" />
  <span>/</span><span>{totalPages}</span>
  <button>→</button>
</div>

🔗 API Reference Tab

The API tab in the playground uses:

• Quick Start Card: card-premium with language selector dropdown (emoji icons, rounded-xl menu).
• Code Block: macOS-style header bar (traffic light dots + language label + copy button), SyntaxHighlighter with no border-radius, transparent background.
• Schema Section: card-premium with blue {} icon header, color-coded Input/Output labels (blue-50/emerald-50), parameter cards with code badges, hover borders, and colored enum/range chips.

🔍 Search Results UI

The global search dropdown uses:

• Container: navbar-glass with backdrop-blur-sm, rounded-2xl, and shadow-2xl.
• Mobile optimization: max-w-[96%] width and top-[60px] positioning on viewports < 640px.
• Items: p-3 (mobile) to p-4 (desktop) cards with slate-100/50 borders.
• Typography: Responsive scaling (text-sm vs text-lg) for balanced legibility.
• Animation: Staggered animate-fade-in-up sequence for result entrance.

✨ Animations & UX

Page Transitions

Use .animate-fade-in-up with staggered delays (.stagger-1 through .stagger-10).

Micro-Interactions

• Buttons: Subtle hover lift (-translate-y-px) and shadow increase.
• Cards: Hover border color transitions (hover:border-slate-200).
• Loading States: Use animate-pulse skeleton rows for table loading.

🛠️ Coding Best Practices

1. Memoization: Always use useCallback for functions passed to children or used in effects.
2. Session Persistence: When fetching user-specific data via axios, include withCredentials: true.
3. Typography: Ensure font-inter (variable) or Inter is applied to all text components.
4. Conditional UI: Hide tabs or actions (like "Embed Code") if the prerequisite data is missing.
5. Mobile First: Use text-xs sm:text-sm and px-3 sm:px-6 patterns — always design for 375px first.