archy/.cursor/rules/UI-STANDARDS.md

Archipelago UI Standards & Coding Rules

Core Design System

Archipelago uses a glassmorphism-based design system with dark backgrounds, subtle transparency, and elegant blur effects. All UI components should follow these established patterns.

---

Standard Interactive Card: .path-option-card

This is our PRIMARY interactive card component. Use this pattern for all selectable/clickable card containers.

Base Styles

.path-option-card {
  position: relative;
  background: rgba(0, 0, 0, 0.60);
  backdrop-filter: blur(24px);
  -webkit-backdrop-filter: blur(24px);
  box-shadow:
    0 8px 24px rgba(0, 0, 0, 0.45),
    inset 0 1px 0 rgba(255, 255, 255, 0.22);
  border-radius: 16px;
  padding: 12px 10px;
  transition: all 0.3s ease;
  cursor: pointer;
  border: none;
}

Gradient Border Effect (Default - Subtle)

.path-option-card::before {
  content: '';
  position: absolute;
  inset: 0;
  border-radius: inherit;
  padding: 2px;
  background: linear-gradient(135deg, rgba(0, 0, 0, 0.8), transparent);
  -webkit-mask: 
    linear-gradient(#fff 0 0) content-box, 
    linear-gradient(#fff 0 0);
  -webkit-mask-composite: xor;
  mask-composite: exclude;
  pointer-events: none;
}

Hover State

.path-option-card:hover {
  transform: translateY(-2px);
  background: rgba(0, 0, 0, 0.35);
  box-shadow:
    0 12px 32px rgba(0, 0, 0, 0.6),
    inset 0 1px 0 rgba(255, 255, 255, 0.25);
}

.path-option-card:hover::before {
  background: linear-gradient(135deg, rgba(255, 255, 255, 0.3), transparent);
}

Selected State

.path-option-card--selected {
  background: rgba(255, 255, 255, 0.12);
  box-shadow:
    0 12px 32px rgba(0, 0, 0, 0.6),
    0 0 30px rgba(255, 255, 255, 0.2),
    inset 0 1px 0 rgba(255, 255, 255, 0.35);
  transform: translateY(-2px);
}

.path-option-card--selected::before {
  background: linear-gradient(135deg, rgba(255, 255, 255, 0.6), transparent);
}

Icon Styling

.path-option-card svg {
  color: rgba(255, 255, 255, 0.85);
  filter: 
    drop-shadow(0 1px 1px rgba(255, 255, 255, 0.3))
    drop-shadow(0 2px 4px rgba(0, 0, 0, 0.8))
    drop-shadow(0 -1px 2px rgba(0, 0, 0, 0.6));
  stroke-width: 2.5;
}

.path-option-card:hover svg {
  color: rgba(255, 255, 255, 1);
  filter: 
    drop-shadow(0 1px 2px rgba(255, 255, 255, 0.5))
    drop-shadow(0 3px 6px rgba(0, 0, 0, 0.9));
}

---

Button Standards

Primary Action Button: .gradient-button

Use for main actions like Launch, Install, Save, Submit

.gradient-button {
  background: linear-gradient(135deg, rgba(255, 255, 255, 0.15) 0%, rgba(0, 0, 0, 0.8) 100%);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
  color: rgba(255, 255, 255, 0.95);
  transition: all 0.3s ease;
}

.gradient-button:hover {
  background: linear-gradient(135deg, rgba(255, 255, 255, 0.2) 0%, rgba(0, 0, 0, 0.9) 100%);
  border-color: rgba(255, 255, 255, 0.3);
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.6);
}

Secondary Action Button: .glass-button

Use for secondary actions like Cancel, Close, Back

.glass-button {
  background-color: rgba(0, 0, 0, 0.6);
  backdrop-filter: blur(18px);
  border: 1px solid rgba(255, 255, 255, 0.18);
  color: rgba(255, 255, 255, 0.9);
  transition: all 0.3s ease;
}

.glass-button:hover {
  color: white;
}

Path Action Button: .path-action-button

Use for onboarding/path selection flows (Continue, Skip)

.path-action-button {
  font-size: 18px;
  font-weight: 500;
  border-radius: 16px;
  background: rgba(0, 0, 0, 0.25);
  color: rgba(255, 255, 255, 0.96);
  box-shadow:
    0 8px 24px rgba(0, 0, 0, 0.45),
    inset 0 1px 0 rgba(255, 255, 255, 0.22);
  backdrop-filter: blur(24px);
  border: none;
  cursor: pointer;
  transition: all 0.3s ease;
}

.path-action-button:hover {
  transform: translateY(-2px);
  background: rgba(0, 0, 0, 0.35);
  box-shadow:
    0 12px 32px rgba(0, 0, 0, 0.6),
    inset 0 1px 0 rgba(255, 255, 255, 0.25);
}

---

Container Standards

Glass Card: .glass-card

Use for content containers, modals, panels

.glass-card {
  background-color: rgba(0, 0, 0, 0.65);
  backdrop-filter: blur(18px);
  -webkit-backdrop-filter: blur(18px);
  border: 1px solid rgba(255, 255, 255, 0.18);
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
  border-radius: 1rem;
  overflow-x: hidden;
  overflow-y: visible;
}

Gradient Card: .gradient-card

Use for featured content, highlighted sections

.gradient-card {
  background: linear-gradient(135deg, rgba(255, 255, 255, 0.1) 0%, rgba(0, 0, 0, 0.8) 100%);
  backdrop-filter: blur(18px);
  border: 1px solid rgba(255, 255, 255, 0.15);
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
  border-radius: 1rem;
}

---

Color Palette

Primary Colors

• White text: rgba(255, 255, 255, 0.9) (primary)
• White text hover: rgba(255, 255, 255, 1) (full white)
• Muted text: rgba(255, 255, 255, 0.6) - rgba(255, 255, 255, 0.7)

Background Colors

• Dark overlay: rgba(0, 0, 0, 0.8) - rgba(0, 0, 0, 0.9)
• Glass background: rgba(0, 0, 0, 0.6) - rgba(0, 0, 0, 0.65)
• Light glass: rgba(0, 0, 0, 0.35)

Border Colors

• Subtle border: rgba(255, 255, 255, 0.18)
• Prominent border: rgba(255, 255, 255, 0.2) - rgba(255, 255, 255, 0.3)

Accent Colors

• Orange (Bitcoin/sync): #fb923c - #f59e0b
• Green (success): #4ade80
• Red (danger): #ef4444
• Blue (info): #3b82f6

---

Animation Standards

Transitions

• Standard: all 0.3s ease
• Fast: all 0.15s ease
• Slow: all 0.5s ease-in-out

Transform on Hover

transform: translateY(-2px);

Transform on Active/Click

transform: translateY(1px);

---

Blur Effects

• Standard blur: blur(18px)
• Strong blur: blur(24px) - blur(40px)
• Light blur: blur(10px)

---

Shadow Standards

Card Shadows

/* Default */
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);

/* Hover */
box-shadow: 0 12px 32px rgba(0, 0, 0, 0.6);

/* With inset highlight */
box-shadow:
  0 8px 24px rgba(0, 0, 0, 0.45),
  inset 0 1px 0 rgba(255, 255, 255, 0.22);

---

Icon Guidelines

Icon Shadow Effects

filter: 
  drop-shadow(0 1px 1px rgba(255, 255, 255, 0.3))
  drop-shadow(0 2px 4px rgba(0, 0, 0, 0.8))
  drop-shadow(0 -1px 2px rgba(0, 0, 0, 0.6));

Icon Colors

• Default: rgba(255, 255, 255, 0.85)
• Hover: rgba(255, 255, 255, 1)
• Muted: rgba(255, 255, 255, 0.6)

Stroke Width

• Standard: 2.5
• Thin: 2
• Bold: 3

---

Usage Rules

DO:

✅ Use .path-option-card for all interactive/selectable cards
✅ Use .gradient-button for primary actions
✅ Use .glass-card for content containers
✅ Add subtle translateY(-2px) on hover
✅ Use backdrop-filter: blur() for glass effects
✅ Include inset highlights: inset 0 1px 0 rgba(255, 255, 255, 0.22)
✅ Use gradient borders with CSS masks for subtle elevation
✅ Maintain 0.3s ease transitions for smooth interactions

DON'T:

❌ Create custom card styles - extend existing ones
❌ Use solid backgrounds - always use transparency + blur
❌ Ignore hover states - all interactive elements need hover feedback
❌ Mix different border styles - use gradient mask or single border
❌ Use hard shadows - keep shadows soft with blur
❌ Forget -webkit-backdrop-filter for Safari support

---

Responsive Considerations

Mobile Adjustments

• Reduce padding by ~25% on small screens
• Reduce blur slightly for performance (blur(12px) instead of blur(18px))
• Simplify animations (consider prefers-reduced-motion)
• Touch targets minimum 44x44px

Breakpoints

/* Mobile first */
sm: 640px   /* Small tablets */
md: 768px   /* Tablets */
lg: 1024px  /* Desktops */
xl: 1280px  /* Large desktops */

---

Accessibility

• Ensure sufficient contrast (WCAG AA minimum)
• Include :focus-visible states matching :hover
• Use semantic HTML (<button>, <nav>, etc.)
• Include ARIA labels where needed
• Support keyboard navigation

---

File Locations

• Global styles: /neode-ui/src/style.css
• Component styles: Scoped <style> blocks in .vue files
• Tailwind config: /neode-ui/tailwind.config.js
• Assets: /neode-ui/public/assets/

---

Version

Last updated: 2026-02-03
Archipelago UI Standards v1.0