# Design Language — Marijus Projects

> Internal reference for maintaining visual consistency across lysiu.com, tokara.dev, and realtalkwith.me.
> Access this anytime at `lysiu.com/design-language.md`

---

## Table of Contents

1. [Philosophy](#philosophy)
2. [Tech Stack Patterns](#tech-stack-patterns)
3. [Color System](#color-system)
4. [Typography](#typography)
5. [Spacing & Layout](#spacing--layout)
6. [Border & Radius](#border--radius)
7. [Shadows & Depth](#shadows--depth)
8. [Glassmorphism & Transparency](#glassmorphism--transparency)
9. [Animations & Transitions](#animations--transitions)
10. [Component Patterns](#component-patterns)
11. [Background Effects](#background-effects)
12. [Responsive Design](#responsive-design)
13. [Dark Mode Strategy](#dark-mode-strategy)
14. [Per-Project Specifics](#per-project-specifics)
15. [Quick Reference Cheatsheet](#quick-reference-cheatsheet)

---

## Philosophy

All projects share a core design ethos:

- **Dark-first.** Every project defaults to dark mode. Dark backgrounds with high-contrast light text.
- **Monochromatic + one accent.** Each project uses a near-black-to-white spectrum with a single bold accent color for interactive elements and emphasis.
- **No CSS frameworks.** Pure CSS with CSS custom properties (variables) for design tokens. CSS Modules for component scoping. No Tailwind, no styled-components on web.
- **Depth through subtlety.** Glassmorphism, soft glows, layered shadows, and semi-transparent surfaces rather than hard borders or flat cards.
- **Motion with purpose.** Animations serve function (scroll reveals, hover feedback, state changes) — never decorative. Premium easing curves over linear/default.
- **Typography-driven hierarchy.** Weight and size differentiate content levels. Color is secondary to structural typography.
- **Minimalism with warmth.** Restrained palettes, generous whitespace, but warm whites and organic curves to avoid clinical coldness.

---

## Tech Stack Patterns

| Concern | Pattern |
|---------|---------|
| Framework | React (19+) with TypeScript or JavaScript |
| Build tool | Vite |
| Styling | CSS custom properties + CSS Modules (web) / NativeWind + StyleSheet (mobile) |
| Fonts | Google Fonts CDN (Poppins, Inter) or system stack |
| Icons | lucide-react / lucide-react-native |
| State | Zustand (when needed) |
| Backend | Supabase or Express + Prisma |
| Hosting | Hostinger (static), Vercel/Fly (dynamic) |

---

## Color System

### Shared Principles

- Background: true black (`#000000`) or near-black (`#0c0a0e` to `#121218`)
- Text: warm off-white (`#f0ede8` to `#fafafa`), never pure `#ffffff`
- Secondary text: muted gray with warm undertones
- One accent color per project, used sparingly
- Semantic colors shared: danger red `#EF4444`, success green `#22c55e`

### Per-Project Palettes

#### lysiu.com — Purple Accent

```css
--bg:             #121218        /* Deep dark */
--bg-elevated:    #1c1c26        /* Raised surfaces */
--bg-card:        #181822        /* Card backgrounds */
--border:         rgba(255,255,255,0.10)
--border-hover:   rgba(255,255,255,0.20)
--text:           #f4f4f6        /* Primary text */
--text-secondary: #b8b8c6        /* Secondary */
--text-muted:     #787890        /* Tertiary */
--accent:         #8958FE        /* Purple */
--color-green:    #22c55e        /* Status only */
--nav-backdrop:   rgba(18,18,24,0.85)
```

Brand colors: `#3483FA` (blue), `#8958FE` (purple), `#46D9FF` (cyan) — used in gradient orbs and background effects.

#### tokara.dev — Rose/Red Accent

```css
/* Dark mode (default) */
--bg:             #0c0a0e        /* Purple-black */
--bg-raised:      #161218        /* Raised surfaces */
--bg-card:        #161218        /* Cards */
--bg-hover:       #201a22        /* Hover state */
--border:         #342030        /* Border */
--border-hover:   #4e2a3c        /* Border hover */
--text:           #fafafa        /* Primary text */
--text-secondary: #d4c0c8        /* Mauve secondary */
--text-muted:     #8a6070        /* Muted mauve */
--primary:        #e11d48        /* Rose-600 */
--primary-hover:  #be123c        /* Rose-700 */
--primary-bg:     rgba(225,29,72,0.1)
--accent:         #fb7185        /* Rose-400 */
--danger:         #ef4444
--success:        #22c55e
--radius:         12px
--radius-sm:      8px
--radius-lg:      16px

/* Light mode */
--bg:             #fafafa
--bg-raised:      #ffffff
--text:           #0a0608
--text-secondary: #4a4a4a
--text-muted:     #8a8a8a
/* Primary/accent colors stay consistent */
```

#### realtalkwith.me — Monochrome + Green Accent

```css
/* App (React Native) */
primary:       '#f0ede8'       /* Warm white */
background:    '#000000'       /* True black */
surface:       '#111111'       /* Dark gray */
surfaceLight:  '#1A1A1A'       /* Lighter surface */
text:          '#f0ede8'       /* Warm white */
textSecondary: '#666666'       /* Mid gray */
danger:        '#EF4444'
promptGreen:   '#22C55E'       /* Only color besides grayscale */

/* Landing page */
--bg:          #000000
--surface:     #0f0f0f
--line:        #1b1b1b
--text:        #f0ede8
--muted:       #7f7a73
--green:       #7cff77          /* Neon green accent */
```

---

## Typography

### Font Families

| Project | Primary | Mono |
|---------|---------|------|
| lysiu | Poppins (400, 500, 600, 700) | JetBrains Mono |
| tokara | Inter (400, 500, 600, 700, 800) | JetBrains Mono / Fira Code / Cascadia Code |
| realtalk | System stack (-apple-system, etc.) | — |

### Size Scale

Use `clamp()` for responsive headings. Fixed sizes for body and UI.

```
Hero title:     clamp(3.2rem, 7vw, 6rem)    — bold 600-800
Section title:  1.8rem – 2rem               — bold 600-800
Subheading:     1.2rem – 1.35rem            — semi-bold 600
Body:           0.85rem – 1rem              — regular 400-500
Labels:         0.75rem – 0.85rem           — mono, uppercase, tracking 0.15em
Tags/pills:     0.72rem – 0.78rem           — mono
Captions:       0.65rem – 0.75rem           — muted color
```

### Letter Spacing

```
Headings:       -0.02em to -0.04em   (tighter)
Body:           0 to 0.04em          (default)
Labels/caps:    0.08em to 0.2em      (loose, uppercase)
```

### Line Heights

```
Headings:       0.95 – 1.2   (tight)
Body:           1.6 – 1.85   (generous)
Code:           1.5 – 1.65
```

---

## Spacing & Layout

### Spacing Scale

```
4px   (xs)     — micro spacing, internal padding
8px   (sm)     — small gaps, icon margins
12px           — between related items
16px  (md)     — standard padding, component gaps
24px  (lg)     — generous padding, section sub-gaps
32px  (xl)     — large section spacing
48px           — between major sections
64px+          — hero/section vertical padding (5rem–7rem)
```

### Container Widths

```
Max content:    1100px – 1280px
Hero content:   900px (centered)
Section:        max-width with 2rem–3rem horizontal padding
```

### Grid Patterns

```
Hero:           1.2fr 1fr (content + visual) or centered single column
Features:       repeat(3, 1fr) → 1fr on mobile
Projects:       80px 1fr (number + content) with nested grids
Cards:          repeat(2, 1fr) or repeat(4, 1fr) depending on content
Gap:            1.25rem – 1.5rem between grid items
```

---

## Border & Radius

### Radius Scale

```
6px   (pill)   — tags, small pills
8px   (sm)     — buttons, inputs, small components
10px  (base)   — standard elements
12px  (md)     — cards, containers
16px  (lg)     — large containers, modals
20px           — sheet/modal top corners
9999px (full)  — perfect circles, pill buttons
```

### Border Style

- Always `1px solid` (occasionally `0.5px` on mobile for retina)
- Color from CSS variable (`--border`), typically 10% white opacity or themed gray
- Hover: border brightens (higher opacity or lighter color)
- Focus: border becomes accent/primary color
- Never use thick borders — always 1px

---

## Shadows & Depth

### Shadow Hierarchy

```css
/* Elevation 1 — subtle */
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);

/* Elevation 2 — cards at rest */
box-shadow: 0 2px 12px rgba(0, 0, 0, 0.1);

/* Elevation 3 — cards on hover */
box-shadow: 0 4px 16px rgba(0, 0, 0, 0.15);

/* Elevation 4 — modals, popovers */
box-shadow: 0 8px 30px rgba(0, 0, 0, 0.2);

/* Elevation 5 — hero elements */
box-shadow: 0 8px 40px rgba(0, 0, 0, 0.3);

/* Accent glow — featured/interactive elements */
box-shadow: 0 0 30px rgba(ACCENT, 0.2), 0 8px 30px rgba(0, 0, 0, 0.3);

/* Button glow */
box-shadow: 0 4px 20px rgba(ACCENT, 0.3);
```

### Depth Strategy

- Use shadows sparingly on dark backgrounds — borders carry more weight
- Accent-colored glow for interactive/featured elements on hover
- Combine elevation shadow + glow for maximum emphasis
- RealTalk uses borders instead of shadows almost exclusively

---

## Glassmorphism & Transparency

### Navigation Bar (all projects)

```css
background: rgba(BG_COLOR, 0.85);
backdrop-filter: blur(12px–24px);
-webkit-backdrop-filter: blur(12px–24px);
border-bottom: 1px solid var(--border);
position: sticky;
z-index: 100;
```

### Surface Transparency

```css
/* Card surfaces */
background: rgba(255, 255, 255, 0.02–0.06);  /* very subtle lift */

/* Accent overlays */
background: rgba(ACCENT, 0.08–0.1);  /* tinted backgrounds */

/* Modal overlays */
background: rgba(0, 0, 0, 0.5–0.6);

/* Status backgrounds */
background: rgba(ACCENT, 0.1);  /* pill/badge backgrounds */
```

---

## Animations & Transitions

### Timing

```
0.1s   — instant feedback (opacity, active states)
0.15s  — fast interactions (border, color changes)
0.2s   — standard hover (buttons, cards, text)
0.3s   — medium transitions (expanded states, navigation)
0.8s   — scroll reveals
1.2s   — decorative animations (divider lines)
```

### Easing

```css
/* Standard */
ease, ease-out, ease-in-out

/* Premium (use for scroll reveals, major transitions) */
cubic-bezier(0.16, 1, 0.3, 1)
```

### Core Animations

#### Scroll Reveal (reusable across projects)

```css
.reveal {
  opacity: 0;
  transform: translateY(20px–30px);
  transition: opacity 0.8s cubic-bezier(0.16, 1, 0.3, 1),
              transform 0.8s cubic-bezier(0.16, 1, 0.3, 1);
}
.reveal.visible {
  opacity: 1;
  transform: translateY(0);
}
/* Stagger children with animation-delay: 0.1s increments */
```

#### Fade Up (for lists, grids)

```css
@keyframes fadeUp {
  from { opacity: 0; transform: translateY(12px); }
  to   { opacity: 1; transform: translateY(0); }
}
/* Apply with staggered --delay custom property */
```

#### Hover Lift

```css
/* Subtle — buttons */
transform: translateY(-1px);

/* Medium — cards */
transform: translateY(-2px);
box-shadow: /* elevated shadow */;
```

#### Modal/Toast Enter

```css
@keyframes modalIn {
  from { opacity: 0; transform: translateY(16px) scale(0.97); }
  to   { opacity: 1; transform: translateY(0) scale(1); }
}
/* Duration: 0.2s ease */
```

#### Shimmer Loading

```css
@keyframes shimmer {
  0%   { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}
background: linear-gradient(90deg, var(--bg-card) 25%, var(--border) 50%, var(--bg-card) 75%);
background-size: 200% 100%;
animation: shimmer 1.5s ease infinite;
```

#### Link Underline Expand

```css
a::after {
  content: '';
  position: absolute;
  bottom: -2px;
  left: 0;
  width: 0;
  height: 1px;
  background: var(--accent);
  transition: width 0.3s ease;
}
a:hover::after {
  width: 100%;
}
```

---

## Component Patterns

### Cards

```css
.card {
  background: var(--bg-card);
  border: 1px solid var(--border);
  border-radius: 12px;
  padding: 1.5rem – 2rem;
  transition: all 0.2s–0.3s ease;
}
.card:hover {
  border-color: var(--border-hover);
  transform: translateY(-2px);
  box-shadow: /* elevated + optional glow */;
}
```

### Buttons

```css
/* Primary */
.btn-primary {
  background: var(--accent);
  color: #000 or #fff;         /* contrast with accent */
  padding: 0.6rem 1.2rem;
  border-radius: 8px;
  font-weight: 600;
  font-size: 0.85rem–0.95rem;
  border: none;
  transition: all 0.2s;
}
.btn-primary:hover {
  transform: translateY(-1px);
  box-shadow: 0 4px 20px rgba(ACCENT, 0.3);
}

/* Secondary / Ghost */
.btn-secondary {
  background: transparent;
  border: 1px solid var(--border);
  color: var(--text);
  /* same padding/radius */
}
.btn-secondary:hover {
  border-color: var(--border-hover);
  background: var(--bg-hover);
}

/* Pill variant (RealTalk) */
border-radius: 999px;
```

### Inputs

```css
input {
  padding: 0.6rem 0.85rem;
  background: var(--bg);
  border: 1px solid var(--border);
  border-radius: 8px;
  color: var(--text);
  font-size: 0.85rem–0.9rem;
  outline: none;
  transition: border-color 0.15s;
}
input:focus {
  border-color: var(--accent);
}
```

### Badges / Pills

```css
.badge {
  display: inline-flex;
  align-items: center;
  gap: 0.4rem;
  padding: 0.3rem 0.8rem;
  font-family: monospace;
  font-size: 0.78rem;
  border: 1px solid var(--border);
  border-radius: 6px;
  color: var(--text-muted);
  transition: all 0.2s;
}
.badge:hover {
  border-color: var(--accent);
  color: var(--accent);
}
```

### Navigation

```css
nav {
  position: sticky;
  top: 0;
  z-index: 100;
  background: var(--nav-backdrop);
  backdrop-filter: blur(16px–24px);
  border-bottom: 1px solid var(--border);
  padding: 1rem 2rem;
  display: flex;
  justify-content: space-between;
  align-items: center;
}
```

### Status Indicator (Online Dot)

```css
/* Green dot with pulsing ripple rings */
.status-dot {
  width: 8px;
  height: 8px;
  border-radius: 50%;
  background: #22c55e;
  box-shadow: 0 0 8px rgba(34, 197, 94, 0.4);
}
/* 3 concentric ripple rings expanding outward */
/* Staggered delays: 0s, 1s, 2s — duration: 3s infinite */
```

---

## Background Effects

### Gradient Orbs (lysiu)

```css
/* Large, blurred radial gradients positioned absolutely */
.orb {
  position: fixed;
  width: 600px–800px;
  height: 600px–800px;
  border-radius: 50%;
  background: radial-gradient(circle, rgba(ACCENT, 0.05–0.06), transparent);
  filter: blur(80px);
  pointer-events: none;
}
```

### Dot Grid (lysiu)

```css
background-image: radial-gradient(circle, rgba(255,255,255,0.05) 1px, transparent 1px);
background-size: 32px 32px;
/* Fade with radial mask */
```

### Film Grain (lysiu)

```css
/* SVG turbulence noise overlay */
opacity: 0.025;
/* Very subtle analog texture */
```

### Gradient Background (RealTalk landing)

```css
background:
  radial-gradient(circle at top, rgba(255,255,255,0.08), transparent 28%),
  linear-gradient(180deg, #090909 0%, #000000 55%, #050505 100%);
```

### macOS Window Chrome (tokara)

```css
/* Colored dots for code blocks */
.dot-red    { background: #ff5f57; }
.dot-yellow { background: #febc2e; }
.dot-green  { background: #28c840; }
/* 12px circles with small gap */
```

---

## Responsive Design

### Breakpoints

```
1024px  — layout adjustments (grid columns reduce)
768px   — primary breakpoint (stack to single column)
640px   — small mobile (reduced padding, tighter spacing)
```

### Mobile Patterns

- All grids collapse to single column at 768px
- Horizontal padding reduces to 1.5rem–2rem
- Hero titles use `clamp()` for fluid scaling
- Navigation becomes hamburger menu
- Touch targets minimum 44px
- `prefers-reduced-motion: reduce` — disable non-essential animations

### Responsive Typography

```css
/* Always use clamp for hero/display text */
font-size: clamp(MIN, PREFERRED_VW, MAX);

/* Example */
font-size: clamp(2.4rem, 5vw, 3.8rem);
```

---

## Dark Mode Strategy

### Default: Dark Only (lysiu, realtalk)

- All colors defined in `:root`
- No light mode toggle
- `prefers-color-scheme` not checked

### Toggle: Dark + Light (tokara)

- Managed via React Context + `data-theme` attribute on `<html>`
- Persisted in `localStorage`
- CSS selectors: `[data-theme="light"] .component { ... }`
- Primary/accent colors stay consistent between themes
- Backgrounds, text, and borders invert
- Semantic colors (success, danger) adjust for contrast in light mode

### When to Support Light Mode

- **Portfolio/personal sites:** Dark only is fine
- **SaaS/tool products:** Support both, dark default
- **Landing pages:** Dark only

---

## Per-Project Specifics

### lysiu.com

- **Accent:** Purple `#8958FE`
- **Unique:** Parallax background video, 3D perspective card hover on mouse move, custom SVG cursor (purple), animated ripple status indicator, divider line reveal animation, film grain overlay
- **Custom cursor:** SVG data URI with `#8958FE` purple circle
- **Premium easing:** `cubic-bezier(0.16, 1, 0.3, 1)` on all major animations

### tokara.dev

- **Accent:** Rose `#e11d48`
- **Unique:** macOS window chrome on code blocks, light mode support, section labels (uppercase, small, accent colored above titles), glow shadows on card hover, drop zone UI with dashed borders
- **Monospace:** JetBrains Mono for all code/terminal content
- **Docs layout:** 260px fixed sidebar + flexible content area

### realtalkwith.me

- **Accent:** Warm white `#f0ede8` (monochromatic) with green `#7cff77` landing / `#22C55E` app
- **Unique:** Voice-first UI with waveform visualization, reel-style full-screen vertical feed, haptic feedback patterns (light/medium/heavy), on-device transcription, single reaction type (heart only)
- **Mobile-first:** React Native + Expo, NativeWind
- **Deliberate restraint:** Only two functional colors (green for live, red for danger)

---

## Quick Reference Cheatsheet

### Starting a New Project

```css
:root {
  /* Backgrounds */
  --bg:             #0a0a0f;
  --bg-elevated:    #141420;
  --bg-card:        #111118;
  --bg-hover:       #1a1a28;

  /* Borders */
  --border:         rgba(255, 255, 255, 0.10);
  --border-hover:   rgba(255, 255, 255, 0.20);

  /* Text */
  --text:           #f4f4f6;
  --text-secondary: #b0b0c0;
  --text-muted:     #606078;

  /* Accent — pick ONE per project */
  --accent:         #YOUR_COLOR;
  --accent-hover:   #YOUR_DARKER;
  --accent-bg:      rgba(YOUR_COLOR, 0.1);

  /* Semantic */
  --danger:         #EF4444;
  --success:        #22c55e;

  /* Radius */
  --radius-sm:      8px;
  --radius:         12px;
  --radius-lg:      16px;

  /* Nav */
  --nav-backdrop:   rgba(10, 10, 15, 0.85);
}

* { box-sizing: border-box; margin: 0; padding: 0; }
html { scroll-behavior: smooth; }
body {
  font-family: 'Poppins', system-ui, -apple-system, sans-serif;
  background: var(--bg);
  color: var(--text);
  line-height: 1.6;
  -webkit-font-smoothing: antialiased;
}
```

### Accent Color Guidelines

| Mood | Color | Hex |
|------|-------|-----|
| Creative / Personal | Purple | `#8958FE` |
| Bold / Technical | Rose/Red | `#e11d48` |
| Minimal / Clean | Warm White | `#f0ede8` |
| Status / Alive | Green | `#22c55e` |
| Trust / Corporate | Blue | `#3483FA` |
| Futuristic | Cyan | `#46D9FF` |

### Animation Defaults

```css
/* Put this on every interactive element */
transition: all 0.2s ease;

/* Scroll reveal — apply via IntersectionObserver */
.reveal         { opacity: 0; transform: translateY(24px); transition: all 0.8s cubic-bezier(0.16, 1, 0.3, 1); }
.reveal.visible { opacity: 1; transform: translateY(0); }

/* Stagger children */
.reveal.delay-1 { transition-delay: 0.1s; }
.reveal.delay-2 { transition-delay: 0.2s; }
.reveal.delay-3 { transition-delay: 0.3s; }
.reveal.delay-4 { transition-delay: 0.4s; }
```

### Do / Don't

| Do | Don't |
|----|-------|
| Use CSS custom properties for all colors | Hardcode hex values in components |
| One accent color per project | Use rainbow of colors |
| `backdrop-filter: blur()` for nav/overlays | Opaque navigation bars |
| `translateY(-1px)` hover lift | Large, jarring hover transforms |
| Warm whites (`#f0ede8`, `#f4f4f6`) | Pure white (`#ffffff`) for text |
| `cubic-bezier(0.16, 1, 0.3, 1)` for reveals | Linear or default easing on scroll animations |
| Monospace for labels, tags, metadata | Monospace for body text |
| Subtle glow shadows with accent color | Hard drop shadows |
| 1px solid borders | Thick borders or outlines |
| `clamp()` for responsive headings | Fixed font sizes for display text |

---

*Last updated: 2026-04-07*
*Generated from: lysiu, tokaradev, testosterostera codebases*