Primora/project_frontend.md

PRIMORA — Frontend System Architecture (SolidJS / React Hybrid)

A modern, developer-focused UI system for Primora.

---

Table of Contents

• 🧠 Frontend Philosophy
• ⚙️ Tech Stack
  • Default Stack (Primary)
  • Fallback Stack
• UI Libraries
• 🎨 UI System Design
  • Core Visual Language
  • Color System
  • Grid System
  • Core UI Components
• ⚡ Interaction Design
• ♿ Accessibility
• 📱 Responsiveness
• 🧠 Component Strategy
• 🚀 Summary

---

🧠 Frontend Philosophy

• UI is a control surface, not decoration
• Everything is data-first
• Navigation is project-centric
• Components are reusable system blocks
• Minimal runtime overhead

---

⚙️ Tech Stack

Default Stack (Primary)

• SolidJS (preferred)
• Vite
• TypeScript (strict mode)
• Tailwind CSS

Fallback Stack

React is ONLY used when:

• The ecosystem requires it
• A third-party library is React-only
• Migration constraints exist

---

UI Libraries

• Ark UI (Solid)
• shadcn-solid (preferred implementation layer)
• shadcn/ui (React fallback)

---

🎨 UI System Design

Core Visual Language

• Dark-first UI system
• Blue accent: #19a3d9
• Card-based layout system
• Soft borders, minimal shadows
• High contrast typography hierarchy

Color System

:root {
  --bg-main: #131315;
  --bg-subtle: #19191c;
  --bg-elevated: #1d1d21;

  --surface-2: #2d2d31;
  --surface-3: #4a4a4d;

  --border: #252529;
  --border-strong: #3e3e42;

  --text-primary: #ededf0;
  --text-secondary: #bebec4;
  --text-muted: #5b5b5f;

  --accent: #19a3d9;
}

Typography

• Primary: Inter
• Brand: Aeonik Pro
• Mono: Fira Code

Hierarchy:

• H1: product pages
• H2: sections
• H3: cards
• body: default
• small: metadata

🧱 Layout System

Global Layout Pattern

Sidebar → Context Header → Content Grid → Detail Panels

Grid System

• 12-column responsive grid
• Auto-fit dashboard cards

.grid {
  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
}

Spacing System

• Base unit: 8px
• Card padding: 16–24px
• Section spacing: 24–40px

Border Radius

:root {
  --radius: 12px;
}

Applied consistently across:

• Cards
• Inputs
• Buttons
• Modals

🧩 Core UI Components

1. Dashboard Card

   • Used for:
     • Metrics
     • Stats
     • Charts
   • Structure:
     • Label (muted)
     • Value (primary)
     • Optional chart

2. Sidebar Navigation

   • Persistent left layout
   • Icon + label
   • Active state highlight (accent background)
   • Collapsible groups

   Active state:

   background: rgba(25, 163, 217, 0.12);
   border-left: accent line;
   

3. Tables

   • Used for:
     • Users
     • Logs
     • Files
     • API keys
   • Design:
     • Minimal borders
     • Hover highlight
     • Compact spacing
     • Fast scan readability

4. File Explorer UI

   • Tree navigation (left)
   • File list (center)
   • Optional preview panel (right)

   Features:

   • Drag & drop upload
   • Streaming upload
   • Instant metadata fetch

5. Charts

   • Minimal grid lines
   • Single accent color
   • No heavy gradients
   • Focus on readability

6. Buttons

   • Primary:

     background: #19a3d9;
     color: white;
     

   • Secondary:

     background: surface-based;
     border: subtle border;
     

---

⚡ Interaction Design

• Hover: 150ms ease
• Modal open: 200ms
• No excessive animations
• Instant navigation priority

---

♿ Accessibility

Mandatory Features:

• Full ARIA labeling
• Keyboard navigation support
• Visible focus states
• Contrast compliance (WCAG AA minimum)
• Screen reader compatibility

---

📱 Responsiveness

• Mobile-first layout scaling
• Sidebar collapses into drawer
• Tables become stacked cards on small screens
• Charts remain responsive

---

🧠 Component Strategy

• Fully reusable primitives
• No page-specific UI components
• Composition over inheritance
• Predictable props structure

---

🚀 Summary

Primora frontend is:

A fast, accessible, system-driven developer UI built with SolidJS-first architecture and React compatibility fallback.

It prioritizes:

• Speed
• Clarity
• Accessibility
• Consistency
• Developer ergonomics