socktop-webterm/CATPPUCCIN_STYLING.md

# Catppuccin Frappe Styling Guide

## Overview

The socktop website now uses the beautiful **Catppuccin Frappe** color scheme throughout. This guide documents all the colors and styling conventions used.

## Color Palette

### Base Colors
```css
--ctp-base: #303446;      /* Main background */
--ctp-mantle: #292c3c;    /* Slightly darker background */
--ctp-crust: #232634;     /* Darkest background */
```

### Surface Colors
```css
--ctp-surface0: #414559;  /* UI elements background */
--ctp-surface1: #51576d;  /* Slightly lighter UI elements */
--ctp-surface2: #626880;  /* Even lighter UI elements */
```

### Overlay Colors
```css
--ctp-overlay0: #737994;  /* Disabled text */
--ctp-overlay1: #838ba7;  /* Comments, secondary text */
--ctp-overlay2: #949cbb;  /* Tertiary text */
```

### Text Colors
```css
--ctp-text: #c6d0f5;      /* Primary text */
--ctp-subtext1: #b5bfe2;  /* Secondary text */
--ctp-subtext0: #a5adce;  /* Tertiary text */
```

### Accent Colors
```css
--ctp-lavender: #babbf1;  /* Links, highlights */
--ctp-blue: #8caaee;      /* Information, primary actions */
--ctp-sapphire: #85c1dc;  /* Special highlights */
--ctp-sky: #99d1db;       /* Sky blue accent */
--ctp-teal: #81c8be;      /* Teal accent */
--ctp-green: #a6d189;     /* Success, positive */
--ctp-yellow: #e5c890;    /* Warnings, attention */
--ctp-peach: #ef9f76;     /* Rust/crates.io theme */
--ctp-maroon: #ea999c;    /* Darker red variant */
--ctp-red: #e78284;       /* Errors, close button */
--ctp-mauve: #ca9ee6;     /* Primary brand color */
--ctp-pink: #f4b8e4;      /* Pink accent */
--ctp-flamingo: #eebebe;  /* Lighter pink */
--ctp-rosewater: #f2d5cf; /* Lightest pink, cursor */
```

## Component Styling

### Hero Title
- **Gradient**: Mauve to Blue (`#ca9ee6` → `#8caaee`)
- **Font**: 3rem, weight 800
- **Effect**: Text gradient with subtle glow
- **Usage**: Main "socktop" heading

### Tagline
- **Color**: `var(--ctp-subtext1)` (#b5bfe2)
- **Font**: 1.25rem, weight 400
- **Usage**: "A TUI-first remote system monitor."

### Link Buttons

#### Base Style
```css
background: rgba(65, 69, 89, 0.6);
border: 1px solid rgba(186, 187, 241, 0.2);
border-radius: 12px;
color: var(--ctp-text);
```

#### GitHub Button
- **Border hover**: `var(--ctp-lavender)` (#babbf1)
- **Shadow hover**: `rgba(186, 187, 241, 0.25)`
- **Icon**: Font Awesome `fab fa-github`

#### Crate Buttons (TUI & Agent)
- **Border hover**: `var(--ctp-peach)` (#ef9f76)
- **Shadow hover**: `rgba(239, 159, 118, 0.25)`
- **Icon**: Font Awesome `fas fa-cube`
- **Theme**: Matches Rust/crates.io orange

#### APT Repository Button
- **Border hover**: `var(--ctp-green)` (#a6d189)
- **Shadow hover**: `rgba(166, 209, 137, 0.25)`
- **Icon**: Font Awesome `fas fa-box`

### Terminal Window

#### Window Frame
```css
background: transparent;
backdrop-filter: blur(20px);
border: 1px solid rgba(186, 187, 241, 0.15);
border-radius: 12px;
box-shadow:
    0 30px 60px rgba(0, 0, 0, 0.4),
    0 12px 24px rgba(0, 0, 0, 0.3),
    inset 0 1px 0 rgba(186, 187, 241, 0.1);
```

#### Title Bar
```css
background: rgba(41, 44, 60, 0.8);
border-bottom: 1px solid rgba(0, 0, 0, 0.3);
height: 44px;
```

#### Traffic Light Buttons
- **Close**: `var(--ctp-red)` (#e78284)
- **Minimize**: `var(--ctp-yellow)` (#e5c890)
- **Maximize**: `var(--ctp-green)` (#a6d189)

#### Terminal Title
```css
color: var(--ctp-subtext1);
font-size: 13px;
font-weight: 500;
```

### Terminal Theme (xterm.js)

```javascript
theme: {
    background: "rgba(48, 52, 70, 0.75)",
    foreground: "#c6d0f5",
    cursor: "#f2d5cf",
    cursorAccent: "#303446",
    selectionBackground: "rgba(202, 158, 230, 0.3)",

    // ANSI colors
    black: "#51576d",
    red: "#e78284",
    green: "#a6d189",
    yellow: "#e5c890",
    blue: "#8caaee",
    magenta: "#f4b8e4",
    cyan: "#81c8be",
    white: "#b5bfe2",

    // Bright ANSI colors
    brightBlack: "#626880",
    brightRed: "#e78284",
    brightGreen: "#a6d189",
    brightYellow: "#e5c890",
    brightBlue: "#8caaee",
    brightMagenta: "#f4b8e4",
    brightCyan: "#81c8be",
    brightWhite: "#a5adce",
}
```

### Header & Footer

#### Header
```css
background: rgba(48, 52, 70, 0.3);
backdrop-filter: blur(10px);
border-bottom: 1px solid rgba(186, 187, 241, 0.1);
```

#### Footer
```css
background: rgba(35, 38, 52, 0.3);
backdrop-filter: blur(10px);
border-top: 1px solid rgba(186, 187, 241, 0.1);
color: var(--ctp-overlay1);
```

#### Footer Links
- **Normal**: `var(--ctp-mauve)` (#ca9ee6)
- **Hover**: `var(--ctp-lavender)` (#babbf1)

## Typography

### Font Families

#### Primary (UI)
```css
font-family: "Inter", "SF Pro Display", -apple-system, BlinkMacSystemFont, 
             "Segoe UI", Roboto, sans-serif;
```

#### Terminal (Monospace)
```css
font-family: "JetBrains Mono", "Fira Code", "Cascadia Code", 
             Consolas, monospace;
```

### Font Sizes
- **Hero Title**: 3rem (48px)
- **Tagline**: 1.25rem (20px)
- **Link Buttons**: 0.95rem (15.2px)
- **Terminal Title**: 13px
- **Terminal Content**: 14px
- **Footer**: 0.875rem (14px)

### Font Weights
- **Hero Title**: 800 (Extra Bold)
- **Tagline**: 400 (Regular)
- **Link Buttons**: 500 (Medium)
- **Terminal Title**: 500 (Medium)

## Effects & Transitions

### Blur Effects
- **Window Frame**: `blur(20px)`
- **Header/Footer**: `blur(10px)`
- **Title Bar**: `blur(10px)`

### Shadows

#### Window Shadow
```css
box-shadow:
    0 30px 60px rgba(0, 0, 0, 0.4),
    0 12px 24px rgba(0, 0, 0, 0.3),
    inset 0 1px 0 rgba(186, 187, 241, 0.1);
```

#### Button Shadow
```css
/* Default */
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);

/* Hover */
box-shadow: 0 8px 24px rgba(202, 158, 230, 0.2);
```

### Transitions
```css
/* Buttons */
transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);

/* Traffic Lights */
transition: all 0.2s ease;

/* Links */
transition: color 0.2s;
```

### Hover Effects

#### Button Hover
```css
transform: translateY(-2px);
/* Plus color-specific shadow and border */
```

#### Traffic Light Hover
- Show inner symbol (×, -, or +)
- Increase brightness slightly

## Transparency & Opacity

### Background Opacities
- **Terminal Background**: `rgba(48, 52, 70, 0.75)` - 75% opaque
- **Title Bar**: `rgba(41, 44, 60, 0.8)` - 80% opaque
- **Header**: `rgba(48, 52, 70, 0.3)` - 30% opaque
- **Footer**: `rgba(35, 38, 52, 0.3)` - 30% opaque
- **Link Buttons**: `rgba(65, 69, 89, 0.6)` - 60% opaque

### Selection Colors
```css
::selection {
    background: var(--ctp-mauve);
    color: var(--ctp-base);
}
```

## Responsive Design

### Mobile (≤480px)
- Logo: 150px max-width
- Hero title: 2rem
- Terminal buttons: 10px diameter
- Title bar: 40px height

### Tablet (≤768px)
- Hero title: 2rem
- Tagline: 1rem
- Link buttons: Full width stack
- Terminal: 8px border radius

## Icon Usage

### Font Awesome Icons
- **GitHub**: `fab fa-github`
- **Crates.io**: `fas fa-cube`
- **APT**: `fas fa-box`
- **Size**: 1.2rem within buttons

## Accessibility

### Contrast Ratios
All text meets WCAG AA standards:
- Primary text on base: High contrast
- Secondary text on base: Medium-high contrast
- Links have distinct colors and hover states

### Focus States
All interactive elements have visible focus states (inherit from Catppuccin theme).

### Screen Readers
- Semantic HTML structure
- ARIA labels on terminal
- Alt text on images
- Descriptive link text

## Customization Tips

### Changing Primary Brand Color

Replace `--ctp-mauve` throughout with another accent:
```css
/* Example: Use blue as primary */
.hero-title {
    background: linear-gradient(135deg, var(--ctp-blue) 0%, var(--ctp-sapphire) 100%);
}

.link-button:hover {
    border-color: var(--ctp-blue);
}
```

### Adjusting Transparency

More opaque terminal:
```css
theme: {
    background: "rgba(48, 52, 70, 0.9)", /* Change from 0.75 */
}
```

Less blur:
```css
backdrop-filter: blur(10px); /* Change from 20px */
```

### Custom Button Colors

Add a new button style:
```css
.link-button.custom {
    border-color: rgba(133, 193, 220, 0.3);
}

.link-button.custom:hover {
    border-color: var(--ctp-sapphire);
    box-shadow: 0 8px 24px rgba(133, 193, 220, 0.25);
}
```

## Resources

- **Catppuccin Official**: https://github.com/catppuccin/catppuccin
- **Catppuccin Frappe**: https://github.com/catppuccin/catppuccin#-frappe
- **Color Palette**: https://catppuccin.com/palette
- **Port Guide**: https://github.com/catppuccin/catppuccin/blob/main/docs/port-creation.md

## Color Reference Chart

```
Base Colors:      Surface Colors:   Overlay Colors:
█ #303446 base    █ #414559 s0      █ #737994 o0
█ #292c3c mantle  █ #51576d s1      █ #838ba7 o1
█ #232634 crust   █ #626880 s2      █ #949cbb o2

Text Colors:      Accent Colors (Part 1):
█ #c6d0f5 text    █ #babbf1 lavender  █ #8caaee blue
█ #b5bfe2 sub1    █ #85c1dc sapphire  █ #99d1db sky
█ #a5adce sub0    █ #81c8be teal      █ #a6d189 green

Accent Colors (Part 2):
█ #e5c890 yellow  █ #ef9f76 peach  █ #ea999c maroon
█ #e78284 red     █ #ca9ee6 mauve  █ #f4b8e4 pink
█ #eebebe flamingo  █ #f2d5cf rosewater
```

---

**Theme**: Catppuccin Frappe  
**Designed for**: socktop web demo  
**Optimized for**: Dark backgrounds with colorful accents