.claude/UI-DESIGN-PRINCIPLES.md

nicholai's ui design principles

these principles are derived from nicholai.work and united tattoo - two projects that share a cohesive design philosophy. use these as guidelines when building ui for nicholai's projects.

foundation: dark-first design

both sites use near-black backgrounds as the foundation. this creates a sophisticated, gallery-like atmosphere.

• primary background: #050505 to #0B0D11 (near-black)
• secondary background: #151921 (slightly lighter for layering)
• text: light gray (#e0e0e0) for body, white for headlines
• always design dark mode first, light mode is secondary

typography hierarchy

use distinct font families for different purposes:

• display/serif: for headlines and emotional impact (Instrument Serif, Sora)
• sans-serif: for body text and readability (Inter, system)
• monospace: for technical elements, labels, metadata (IBM Plex Mono, Geist Mono)

sizing patterns:

• hero headlines: 7xl-9xl with extremely tight line-height (0.85-0.9)
• section headings: 4xl-6xl
• body: base-xl (1rem-1.25rem)
• labels/metadata: xs (10-12px minimum)

uppercase + wide tracking for labels:

• section markers, buttons, and metadata use uppercase
• letter-spacing: 0.15em to 0.3em for label text
• creates visual distinction and hierarchy

color restraint

limited palette with warm accents used surgically:

primary accent family:

• burnt orange: #E67E50 (CTAs, key highlights)
• terracotta: #D87850 (hover states)
• red-orange: #dd4132 (brand accent)

secondary accents:

• sage/moss: #a28f79 to #6f5c49 (icons, subtle labels)
• cyan: #22D3EE (technical highlights, reserved)

rules:

• accents are for emphasis, not decoration
• use sparingly on CTAs, hover states, section markers
• maintain monochrome foundation, color adds hierarchy

border language

subtle borders create structure without visual heaviness:

• default: white/5 to white/10 (5-10% opacity)
• hover: white/20 to white/30
• focus: white/30 to accent color

patterns:

• left accent strips (w-1 bg-accent) for list items
• bottom borders only on form fields
• grid borders at white/5 for structural rhythm
• no rounded corners except circular elements (rounded-full)

texture and depth

subtle overlays create premium feel:

• noise grain: 2-5% opacity procedural noise overlay
• scanlines: linear-gradient at 3% opacity (optional, for tech aesthetic)
• glass cards: rgba(255,255,255,0.02) with backdrop-blur(24px)
• vignettes: radial-gradient for edge softening

never heavy-handed - these should be barely perceptible

spacing philosophy

generous whitespace, museum-quality pacing:

• section padding: py-32 to py-48 (128px-192px)
• component padding: p-6 to p-12 (24px-48px)
• page margins: px-6 mobile, lg:px-12 to lg:px-16 desktop
• gap: gap-6 to gap-12 (24px-48px)

rule: when in doubt, add more space

grid system

12-column grid with asymmetric layouts:

• mobile: single column (grid-cols-1)
• desktop: 12-column with asymmetric splits (4-8, 3-9, 2-10)
• strong vertical rhythm with visible grid lines (white/5)
• sidebar layouts: 2-col sidebar + 10-col content

animation guidelines

purposeful, smooth animations that enhance rather than distract:

easing:

• custom cubic-bezier(0.16, 1, 0.3, 1) for smooth, slight bounce
• power3.out / power4.out for GSAP
• duration: 0.3s for hover, 0.6-0.8s for reveals

scroll animations:

• fade + translateY (30-50px) on scroll into view
• stagger delays: 0.05s to 0.15s between items
• use IntersectionObserver or GSAP ScrollTrigger

parallax:

• subtle yPercent shifts (15-30) for depth
• smooth scrolling with Lenis (1.2s duration)

micro-interactions:

• hover: color transitions, slight translateY(-2px)
• border reveals on hover (transparent to accent)
• scale(1.05-1.1) on interactive elements

section markers

editorial numbering creates structure:

formats:

• [01], [02], [03] for section numbers
• SYS.PRTF, SYS.RECORDS for technical labels
• PRJ.01, EXP.01 for project/experience identifiers

styling:

• monospace font
• 10-12px, uppercase
• wide letter-spacing (0.2em+)
• muted color (sage, moss, neutral-400)

responsive approach

mobile-first with progressive enhancement:

breakpoints (tailwind defaults):

• md: 768px
• lg: 1024px

patterns:

• base styles for mobile, md: and lg: prefixes for desktop
• navigation: hamburger mobile, full nav/sidebar desktop
• font sizes scale at breakpoints (text-6xl md:text-8xl lg:text-9xl)
• hide decorative elements on mobile (hidden lg:block)
• padding scales: px-6 -> md:px-12 -> lg:px-16

interactive states

consistent hover/focus patterns:

buttons:

• primary: accent background, darker on hover, slight lift
• ghost: border only, accent fill on hover
• always rounded-full, monospace uppercase text

cards:

• border lightens on hover (white/10 -> white/20)
• left accent strip scales or glows
• subtle background shift

links:

• underline with offset, accent color on hover
• or: no underline, accent color on hover

forms:

• bottom border only, accent color on focus
• label color shifts white on focus

z-index hierarchy

• background: -1
• base content: 0
• elevated content: 1-10
• navigation: 40
• floating CTAs: 50
• overlays/modals: 100+

quick reference

when building UI for nicholai:

1. start with near-black background
2. establish typography hierarchy (display, body, mono)
3. use warm accents sparingly for emphasis
4. add subtle borders at low opacity
5. apply texture overlays at 2-5%
6. generous spacing throughout
7. smooth, purposeful animations
8. editorial section markers
9. mobile-first responsive
10. consistent hover states