# 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
```css
.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)
```css
.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
```css
.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
```css
.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
```css
.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**

```css
.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**

```css
.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**)

```css
.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

```css
.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

```css
.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
```css
transform: translateY(-2px);
```

### Transform on Active/Click
```css
transform: translateY(1px);
```

---

## Blur Effects

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

---

## Shadow Standards

### Card Shadows
```css
/* 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
```css
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
```css
/* 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
