aurorabot/docs/aurora-admin-design-guidelines.md

Aurora Admin Panel - Design Guidelines

Design Philosophy

The Aurora Admin Panel embodies the intersection of celestial mystique and institutional precision. It is a command center for academy administration—powerful, sophisticated, and unmistakably authoritative. Every interface element should communicate control, clarity, and prestige.

Core Principles:

• Authority over Friendliness: This is an administrative tool, not a consumer app
• Data Clarity: Information density balanced with elegant presentation
• Celestial Aesthetic: Subtle cosmic theming that doesn't compromise functionality
• Institutional Grade: Professional, trustworthy, built to manage complex systems

---

Visual Foundation

Color System

Background Hierarchy

Level 0 (Base)       #0A0A0F  Eclipse Void - Deepest background
Level 1 (Container)  #151520  Midnight Canvas - Cards, panels, modals
Level 2 (Surface)    #1E1B4B  Nebula Surface - Elevated elements
Level 3 (Raised)     #2D2A5F  Stellar Overlay - Hover states, dropdowns

Text Hierarchy

Primary Text         #F9FAFB  Starlight White - Headings, key data
Secondary Text       #E5E7EB  Stardust Silver - Body text, labels
Tertiary Text        #9CA3AF  Cosmic Gray - Helper text, timestamps
Disabled Text        #6B7280  Void Gray - Inactive elements

Brand Accents

Primary (Action)     #8B5CF6  Aurora Purple - Primary buttons, links, active states
Secondary (Info)     #3B82F6  Nebula Blue - Informational elements
Success              #10B981  Emerald - Confirmations, positive indicators
Warning              #F59E0B  Amber - Cautions, alerts
Danger               #DC2626  Crimson - Errors, destructive actions
Gold (Prestige)      #FCD34D  Celestial Gold - Premium features, highlights

Constellation Tier Colors (for data visualization)

Constellation A      #FCD34D  Celestial Gold
Constellation B      #8B5CF6  Aurora Purple
Constellation C      #3B82F6  Nebula Blue
Constellation D      #6B7280  Slate Gray

Semantic Colors

Currency (AU)        #FCD34D  Gold - Astral Units indicators
Currency (CU)        #8B5CF6  Purple - Constellation Units indicators
XP/Progress          #3B82F6  Blue - Experience and progression
Activity             #10B981  Green - Active users, live events

Typography

Font Stack

Primary (UI Text):

font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

• Clean, highly legible, modern
• Excellent at small sizes for data-dense interfaces
• Professional without being sterile

Display (Headings):

font-family: 'Space Grotesk', 'Inter', sans-serif;

• Geometric, slightly futuristic
• Use for page titles, section headers
• Reinforces celestial/institutional theme

Monospace (Data):

font-family: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;

• For numerical data, timestamps, IDs
• Improves scanability of tabular data
• Technical credibility

Type Scale

Display Large    48px / 3rem     font-weight: 700  (Dashboard headers)
Display          36px / 2.25rem  font-weight: 700  (Page titles)
Heading 1        30px / 1.875rem font-weight: 600  (Section titles)
Heading 2        24px / 1.5rem   font-weight: 600  (Card headers)
Heading 3        20px / 1.25rem  font-weight: 600  (Subsections)
Body Large       16px / 1rem     font-weight: 400  (Emphasized body)
Body             14px / 0.875rem font-weight: 400  (Default text)
Body Small       13px / 0.8125rem font-weight: 400 (Secondary info)
Caption          12px / 0.75rem  font-weight: 400  (Labels, hints)
Overline         11px / 0.6875rem font-weight: 600 (Uppercase labels)

Font Weight Usage

• 700 (Bold): Display text, critical metrics
• 600 (Semibold): Headings, emphasized data
• 500 (Medium): Buttons, active tabs, selected items
• 400 (Regular): Body text, form inputs
• Never use weights below 400 - maintain readability

Spacing & Layout

Base Unit: 4px

Spacing Scale

xs   4px   0.25rem   Tight spacing, icon gaps
sm   8px   0.5rem    Form element spacing
md   16px  1rem      Default component spacing
lg   24px  1.5rem    Section spacing
xl   32px  2rem      Major section breaks
2xl  48px  3rem      Page section dividers
3xl  64px  4rem      Major layout divisions

Container Widths

Full Bleed       100%           Full viewport width
Wide             1600px         Wide dashboards, data tables
Standard         1280px         Default content width
Narrow           960px          Forms, focused content
Reading          720px          Long-form text (documentation)

Grid System

• 12-column grid for flexible layouts
• 24px gutters between columns
• Responsive breakpoints: 640px, 768px, 1024px, 1280px, 1536px

Borders & Dividers

Border Widths

Hairline         0.5px          Subtle dividers
Thin             1px            Default borders
Medium           2px            Emphasized borders, focus states
Thick            4px            Accent bars, category indicators

Border Colors

Default          #2D2A5F  15% opacity - Standard dividers
Subtle           #2D2A5F  8% opacity  - Very light separation
Emphasized       #8B5CF6  30% opacity - Highlighted borders
Interactive      #8B5CF6  60% opacity - Hover/focus states

Border Radius

None             0px            Data tables, strict layouts
sm               4px            Buttons, badges, pills
md               8px            Cards, inputs, panels
lg               12px           Large cards, modals
xl               16px           Feature cards, images
2xl              24px           Hero elements
full             9999px         Circular elements, avatars

---

UI Patterns

Cards & Containers

Standard Card

Background:      #151520 (Midnight Canvas)
Border:          1px solid rgba(139, 92, 246, 0.15)
Border Radius:   8px
Padding:         24px
Shadow:          0 4px 16px rgba(0, 0, 0, 0.4)

Elevated Card (hover/focus)

Background:      #1E1B4B (Nebula Surface)
Border:          1px solid rgba(139, 92, 246, 0.3)
Shadow:          0 8px 24px rgba(0, 0, 0, 0.6)
Transform:       translateY(-2px)
Transition:      all 200ms ease

Stat Card (metrics, KPIs)

Background:      Linear gradient from #151520 to #1E1B4B
Border:          1px solid rgba(139, 92, 246, 0.2)
Accent Border:   4px left border in tier/category color
Icon:            Celestial icon in accent color
Typography:      Large number (Display), small label (Overline)

Data Tables

Table Structure

Header Background:   #1E1B4B
Header Text:         #E5E7EB, 11px uppercase, 600 weight
Row Background:      Alternating #0A0A0F / #151520
Row Hover:           #2D2A5F with 40% opacity
Border:              1px solid rgba(139, 92, 246, 0.1) between rows
Cell Padding:        12px 16px

Column Styling

• Left-align text columns
• Right-align numerical columns
• Monospace font for numbers, IDs, timestamps
• Icon + text combinations for status indicators

Interactive Elements

• Sortable headers with subtle arrow icons
• Hover state on entire row
• Click/select highlight with Aurora Purple tint
• Pagination in Nebula Blue

Forms & Inputs

Input Fields

Background:      #1E1B4B
Border:          1px solid rgba(139, 92, 246, 0.2)
Border Radius:   6px
Padding:         10px 14px
Font Size:       14px
Text Color:      #F9FAFB

Focus State:
  Border:        2px solid #8B5CF6
  Glow:          0 0 0 3px rgba(139, 92, 246, 0.2)
  
Error State:
  Border:        1px solid #DC2626
  Text:          #DC2626 helper text below
  
Disabled State:
  Background:    #0A0A0F
  Text:          #6B7280
  Cursor:        not-allowed

Labels

Font Size:       12px
Font Weight:     600
Text Color:      #E5E7EB
Margin Bottom:   6px

Select Dropdowns

Same base styling as inputs
Dropdown Icon:   Chevron in #9CA3AF
Menu Background: #2D2A5F
Menu Border:     1px solid rgba(139, 92, 246, 0.3)
Option Hover:    #3B82F6 background
Selected:        #8B5CF6 with checkmark icon

Checkboxes & Radio Buttons

Size:            18px × 18px
Border:          2px solid rgba(139, 92, 246, 0.4)
Border Radius:   4px (checkbox) / 50% (radio)
Checked:         #8B5CF6 background with white checkmark
Hover:           Glow effect rgba(139, 92, 246, 0.2)

Buttons

Primary Button

Background:      #8B5CF6 (Aurora Purple)
Text:            #FFFFFF
Padding:         10px 20px
Border Radius:   6px
Font Weight:     500
Shadow:          0 2px 8px rgba(139, 92, 246, 0.3)

Hover:
  Background:    #7C3AED (lighter purple)
  Shadow:        0 4px 12px rgba(139, 92, 246, 0.4)
  
Active:
  Background:    #6D28D9 (darker purple)
  Transform:     scale(0.98)

Secondary Button

Background:      transparent
Border:          1px solid rgba(139, 92, 246, 0.5)
Text:            #8B5CF6
Padding:         10px 20px

Hover:
  Background:    rgba(139, 92, 246, 0.1)
  Border:        1px solid #8B5CF6

Destructive Button

Background:      #DC2626
Text:            #FFFFFF
(Same structure as Primary)

Ghost Button

Background:      transparent
Text:            #E5E7EB
Padding:         8px 16px

Hover:
  Background:    rgba(139, 92, 246, 0.1)
  Text:          #8B5CF6

Button Sizes

Small    8px 12px   12px text
Medium   10px 20px  14px text  (default)
Large    12px 24px  16px text

Navigation

Sidebar Navigation

Background:      #0A0A0F with subtle gradient
Width:           260px (expanded) / 64px (collapsed)
Border Right:    1px solid rgba(139, 92, 246, 0.15)

Nav Item:
  Padding:       12px 16px
  Border Radius: 6px
  Font Size:     14px
  Font Weight:   500
  Icon Size:     20px
  Gap:           12px between icon and text
  
Active State:
  Background:    rgba(139, 92, 246, 0.15)
  Border Left:   4px solid #8B5CF6
  Text:          #8B5CF6
  Icon:          #8B5CF6
  
Hover State:
  Background:    rgba(139, 92, 246, 0.08)
  Text:          #F9FAFB

Top Bar / Header

Background:      #0A0A0F with backdrop blur
Height:          64px
Border Bottom:   1px solid rgba(139, 92, 246, 0.15)
Position:        Sticky
Z-index:         100

Contains:
  - Logo / Academy name
  - Global search
  - Quick actions
  - User profile dropdown
  - Notification bell

Breadcrumbs

Font Size:       13px
Text Color:      #9CA3AF
Separator:       "/" or "›" in #6B7280
Current Page:    #F9FAFB, 600 weight
Links:           #9CA3AF, hover to #8B5CF6

Modals & Overlays

Modal Structure

Backdrop:        rgba(0, 0, 0, 0.8) with backdrop blur
Modal Container: #151520
Border:          1px solid rgba(139, 92, 246, 0.2)
Border Radius:   12px
Shadow:          0 24px 48px rgba(0, 0, 0, 0.9)
Max Width:       600px (standard) / 900px (wide)
Padding:         32px

Header:
  Border Bottom: 1px solid rgba(139, 92, 246, 0.15)
  Padding:       0 0 20px 0
  Font Size:     24px
  Font Weight:   600
  
Footer:
  Border Top:    1px solid rgba(139, 92, 246, 0.15)
  Padding:       20px 0 0 0
  Buttons:       Right-aligned, 12px gap

Toast Notifications

Position:        Top-right, 24px margin
Background:      #2D2A5F
Border:          1px solid (color based on type)
Border Radius:   8px
Padding:         16px 20px
Max Width:       400px
Shadow:          0 8px 24px rgba(0, 0, 0, 0.6)

Success:         #10B981 border, green icon
Warning:         #F59E0B border, amber icon
Error:           #DC2626 border, red icon
Info:            #3B82F6 border, blue icon

Animation:       Slide in from right, fade out
Duration:        4 seconds (dismissible)

Data Visualization

Charts & Graphs

Background:      #151520 or transparent
Grid Lines:      rgba(139, 92, 246, 0.1)
Axis Labels:     #9CA3AF, 12px
Data Points:     Constellation tier colors or semantic colors
Tooltips:        #2D2A5F background, white text
Legend:          Horizontal, 12px, icons + labels

Progress Bars

Track:           #1E1B4B
Fill:            Linear gradient with tier/category color
Height:          8px (thin) / 12px (medium) / 16px (thick)
Border Radius:   9999px
Label:           Above or inline, monospace numbers

Badges & Pills

Background:      Semantic color with 15% opacity
Text:            Semantic color (full saturation)
Border:          1px solid semantic color with 30% opacity
Padding:         4px 10px
Border Radius:   9999px
Font Size:       12px
Font Weight:     500

Status Examples:
  Active:        Green
  Pending:       Amber
  Inactive:      Gray
  Error:         Red
  Premium:       Gold

Icons

Icon System

• Use consistent icon family (e.g., Lucide, Heroicons, Phosphor)
• Line-style icons, not filled (except for active states)
• Stroke width: 1.5px-2px
• Sizes: 16px (small), 20px (default), 24px (large), 32px (extra large)

Icon Colors

• Default: #9CA3AF (Cosmic Gray)
• Active/Selected: #8B5CF6 (Aurora Purple)
• Success: #10B981
• Warning: #F59E0B
• Error: #DC2626

Celestial Icon Themes

• Stars, constellations, orbits for branding
• Minimalist, geometric line art
• Avoid overly detailed or realistic astronomy images

---

Animation & Motion

Principles

• Purposeful: Animations guide attention and provide feedback
• Subtle: No distracting or excessive motion
• Fast: Snappy interactions (150-300ms)
• Professional: Ease curves that feel polished

Timing Functions

ease-out         Default for most interactions
ease-in-out      Modal/panel transitions
ease-in          Exit animations
spring           Micro-interactions (subtle bounce)

Standard Durations

Instant          0ms          State changes
Fast             150ms        Button hover, color changes
Standard         200ms        Card hover, dropdown open
Moderate         300ms        Modal open, page transitions
Slow             500ms        Large panel animations

Common Animations

Hover Effects

transition: all 200ms ease-out;
transform: translateY(-2px);
box-shadow: [enhanced shadow];

Focus States

transition: border 150ms ease-out, box-shadow 150ms ease-out;
border-color: #8B5CF6;
box-shadow: 0 0 0 3px rgba(139, 92, 246, 0.2);

Loading States

Skeleton:        Shimmer effect from left to right
Spinner:         Rotating celestial icon or ring
Progress:        Smooth bar fill with easing

Page Transitions

Fade in:         Opacity 0 → 1 over 200ms
Slide up:        TranslateY(20px) → 0 over 300ms
Blur fade:       Blur + opacity for backdrop

---

Responsive Behavior

Breakpoints

Mobile           < 640px
Tablet           640px - 1024px
Desktop          > 1024px
Wide Desktop     > 1536px

Mobile Adaptations

• Sidebar collapses to hamburger menu
• Cards stack vertically
• Tables become horizontally scrollable or convert to card view
• Reduce padding and spacing by 25-50%
• Larger touch targets (minimum 44px)
• Bottom navigation for primary actions

Tablet Optimizations

• Hybrid layouts (sidebar can be toggled)
• Adaptive grid (4 columns → 2 columns)
• Touch-friendly sizing maintained
• Utilize available space efficiently

---

Accessibility

Color Contrast

• Maintain WCAG AA standards minimum (4.5:1 for normal text)
• Critical actions and text meet AAA standards (7:1)
• Never rely on color alone for information

Focus Indicators

• Always visible focus states
• 2px Aurora Purple outline with 3px glow
• Logical tab order follows visual hierarchy

Screen Readers

• Semantic HTML structure
• ARIA labels for icon-only buttons
• Status messages announced appropriately
• Table headers properly associated

Keyboard Navigation

• All interactive elements accessible via keyboard
• Modal traps focus within itself
• Escape key closes overlays
• Arrow keys for navigation where appropriate

---

Dark Mode Philosophy

Aurora Admin is dark-first by design. The interface assumes a dark environment and doesn't offer a light mode toggle. This decision is intentional:

• Focus: Dark reduces eye strain during extended admin sessions
• Data Emphasis: Light text on dark makes numbers/data more prominent
• Celestial Theme: Dark backgrounds reinforce the cosmic aesthetic
• Professional: Dark UIs feel more serious and technical

If light mode is ever required, avoid pure white—use off-white (#F9FAFB) backgrounds with careful contrast management.

---

Theming & Customization

Constellation Tier Theming

When displaying constellation-specific data:

• Use tier colors for accents, not backgrounds
• Apply colors to borders, icons, badges
• Maintain readability—don't overwhelm with color

Admin Privilege Levels

Different admin roles can have subtle UI indicators:

• Super Admin: Gold accents
• Moderator: Purple accents
• Viewer: Blue accents

These are subtle hints, not dominant visual themes.

---

Component Library Standards

Consistency

• Reuse components extensively
• Maintain consistent spacing, sizing, behavior
• Document component variants clearly
• Avoid one-off custom elements

Composability

• Build complex UIs from simple components
• Components should work together seamlessly
• Predictable prop APIs
• Flexible but not overly configurable

Performance

• Lazy load heavy components
• Virtualize long lists
• Optimize re-renders
• Compress and cache assets

---

Code Style (UI Framework Agnostic)

Class Naming

Use clear, semantic names:

.card-stat           Not .cs or .c1
.button-primary      Not .btn-p or .bp
.table-header        Not .th or .t-h

Component Organization

/components
  /ui                Base components (buttons, inputs)
  /layout            Layout components (sidebar, header)
  /data              Data components (tables, charts)
  /feedback          Toasts, modals, alerts
  /forms             Form-specific components

Style Organization

• Variables/tokens for all design values
• No magic numbers in components
• DRY—reuse common styles
• Mobile-first responsive approach

---

Best Practices

Do's ✓

• Use established patterns from these guidelines
• Maintain consistent spacing throughout
• Prioritize data clarity and scannability
• Test with real data, not lorem ipsum
• Consider loading and empty states
• Provide clear feedback for all actions
• Use progressive disclosure for complex features

Don'ts ✗

• Don't use bright, saturated colors outside defined palette
• Don't create custom components when standard ones exist
• Don't sacrifice accessibility for aesthetics
• Don't use decorative animations that distract
• Don't hide critical actions in nested menus
• Don't use tiny fonts (below 12px) for functional text
• Don't ignore error states and edge cases

---

Quality Checklist

Before considering any UI complete:

Visual

• Colors match defined palette exactly
• Spacing uses the 4px grid system
• Typography follows scale and hierarchy
• Borders and shadows are consistent
• Icons are properly sized and aligned

Interaction

• Hover states are defined for all interactive elements
• Focus states are visible and clear
• Loading states prevent user confusion
• Success/error feedback is immediate
• Animations are smooth and purposeful

Responsive

• Layout adapts to mobile, tablet, desktop
• Touch targets are minimum 44px on mobile
• Text remains readable at all sizes
• No horizontal scrolling (except intentional)

Accessibility

• Keyboard navigation works completely
• Focus indicators are always visible
• Color contrast meets WCAG AA minimum
• ARIA labels present where needed
• Screen reader tested for critical flows

Data

• Empty states are handled gracefully
• Error states provide actionable guidance
• Large datasets perform well
• Loading states prevent layout shift

---

Reference Assets

Suggested Icon Library

• Lucide Icons: Clean, consistent, extensive
• Heroicons: Tailwind-friendly, well-designed
• Phosphor Icons: Flexible weights and styles

Font Resources

• Inter: Google Fonts
• Space Grotesk: Google Fonts
• JetBrains Mono: JetBrains

Design Tools

• Use component libraries: shadcn/ui, Headless UI, Radix
• Tailwind CSS for utility-first styling
• CSS variables for theming
• Design tokens for consistency

---

Conclusion

The Aurora Admin Panel is a sophisticated tool that demands respect through its design. Every pixel serves a purpose—whether to inform, to guide, or to reinforce the prestige of the academy it administers.

Design with authority. Build with precision. Maintain the standard.

---

These design guidelines are living documentation. As Aurora evolves, so too should these standards. Propose updates through the standard development workflow.