Skip to content

Instantly share code, notes, and snippets.

@adithyan-ak
Created July 16, 2025 20:47
Show Gist options
  • Select an option

  • Save adithyan-ak/bee63d663f564fa35a79f23098c1a7b4 to your computer and use it in GitHub Desktop.

Select an option

Save adithyan-ak/bee63d663f564fa35a79f23098c1a7b4 to your computer and use it in GitHub Desktop.
Design Philosophy for LLM Systems to follow while generating frontend projects from scratch.

Comprehensive UI/Design System Documentation

This project embodies a modern, minimalist SaaS design language with sophisticated theming capabilities. Here's a detailed breakdown that can serve as a blueprint for recreating this aesthetic:

Design Philosophy

  • Core Principle: Clean minimalism with purposeful complexity
  • Visual Language: Professional SaaS/startup aesthetic with enterprise-grade polish
  • Interaction Model: Subtle animations and micro-interactions that enhance without overwhelming

Color Architecture

Dual-Theme System with Semantic Layers:

The project uses a sophisticated HSL-based color system with three layers:

  1. Base Layer: Core background/foreground contrasts
  2. Semantic Layer: Purpose-driven color mappings (primary, secondary, accent)
  3. Opacity Layer: 20+ opacity variants (5%-100%) for nuanced depth

Light Theme Palette:

  • Canvas: Pure white (#FFFFFF) with off-white surfaces
  • Text Hierarchy: #0A0A0A (primary) → #737373 (secondary) → #A3A3A3 (tertiary)
  • Accent: Dynamic blue (HSL: 213 94% 68%) - customizable via CMS
  • Borders: Subtle #E5E5E5 with 1px precision

Dark Theme Palette:

  • Canvas: Rich black (#0A0A0A) with layered grays
  • Text Hierarchy: #FAFAFA → #A3A3A3 → #737373
  • Accent: Consistent with light theme for brand continuity
  • Borders: #262626 for subtle definition

Typography System

Font Strategy:

  • Primary: "Geist" - A modern geometric sans-serif
  • Secondary: "IBM Plex Serif" - For editorial content
  • System Stack: Optimized fallbacks for performance

Type Scale:

  • Uses custom Tailwind scale (2xs to 9xl)
  • Negative letter-spacing (-0.3px to -3.2px) for optical correction
  • Line heights calculated for optimal readability
  • Font weights limited to 300-500 for consistency

Spatial Design

Layout Grid:

  • 1400px max container width
  • 2rem (32px) horizontal padding
  • 8px base unit for all spacing
  • Custom grid patterns for complex layouts

Component Spacing:

  • Buttons: 32px (md) and 40px (lg) heights
  • Border radius: 0.5rem default, with sm/md/lg variants
  • Consistent padding ratios across components

Animation & Effects

Motion Principles:

  • Duration: 150-200ms for micro-interactions
  • Easing: Tailwind's default curves
  • Stagger delays for sequential animations

Signature Effects:

  • Blur filters (100px, 200px variants) for depth
  • Neon box-shadows for emphasis
  • Moving line animations for visual interest
  • Accordion transitions via Radix UI

Component Architecture

Button System (CVA-based): Variants:

  • primary: Accent background, inverted text
  • secondary: Muted background, primary text
  • tertiary: Transparent with borders
  • ghost: Minimal with hover states

States:

  • Hover: Subtle brightness shifts
  • Focus: Visible outline for accessibility
  • Disabled: Reduced opacity

Form Elements:

  • Consistent heights matching button sizes
  • Subtle borders with focus states
  • Error states with semantic colors

Theme Implementation

Technical Stack:

  • next-themes for theme switching
  • CSS variables for runtime theming
  • BaseHub CMS for dynamic customization
  • Tailwind for utility classes

CSS Architecture:

  • Global styles split between app/ and styles/
  • Component modules for complex animations
  • Utility-first with escape hatches
  • Custom properties for all dynamic values

Visual Patterns

Decorative Elements:

  • Grid backgrounds for texture
  • Gradient overlays for depth
  • Blur backdrops for layering
  • Animated accents for engagement

Content Presentation:

  • Card-based layouts with subtle shadows
  • Clear visual hierarchy
  • Generous whitespace
  • Focus on readability

Responsive Strategy

Breakpoints:

  • Mobile-first approach
  • sm: 640px, md: 768px, lg: 1024px, xl: 1280px, 2xl: 1536px
  • Fluid typography with clamp()
  • Progressive enhancement for decorative elements

Implementation Blueprint

To recreate this design system:

  1. Foundation: Next.js 14+ with App Router
  2. Styling: Tailwind CSS 3+ with custom configuration
  3. Components: shadcn/ui as base, enhanced with CVA
  4. Theming: CSS variables + next-themes
  5. Typography: Variable fonts with optical adjustments
  6. Animation: Framer Motion or CSS modules
  7. Icons: Lucide React for consistency
  8. CMS: BaseHub or similar for dynamic theming

This design system prioritizes clarity, flexibility, and performance while maintaining a sophisticated visual presence suitable for modern SaaS applications.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment