Design Philosophy

This document serves as the definitive guide for building and maintaining UI components in our project. ALL components MUST strictly follow these guidelines.

Table of Contents

Core Philosophy

Design System Principles

1. Building Block First

ALWAYS use components from ~/components/basic-ui/building-blocks.tsx as your foundation. Never use raw <div> elements when a building block exists.

2. Semantic Color Tokens

ALWAYS use semantic color classes (bg-background, text-foreground, border-accent-foreground) instead of direct Tailwind colors (bg-blue-500). This ensures proper theme support and maintainability.

3. Viewport Units Over Pixels

Prefer viewport units (vh, vw) and relative spacing over fixed pixel values for responsive scaling across all screen sizes.

4. Responsive-First Typography

Use the custom typography system (text-default, text-lg, text-xl) which automatically scales across breakpoints.

5. CSS Variables for Scale

The entire system is built on mathematical ratios and CSS variables that ensure consistent scaling from mobile (360px) to ultra-wide (3840px+) displays.

Building Block Components

All layout components are imported from ~/components/basic-ui/building-blocks.tsx. These are the ONLY way to structure layouts.

Core Layout Components

Box

Base container component. Use for generic wrappers.

import { Box } from "~/components/basic-ui/building-blocks";

<Box className="p-[2vh] rounded-xl">Content here</Box>

Flex

Flexible container with display: flex.

import { Flex } from "~/components/basic-ui/building-blocks";

<Flex className="items-center justify-between gap-[1vh]">
  <div>Left content</div>
  <div>Right content</div>
</Flex>

VStack / VStackFull

Vertical stack (flex-col) for stacking items vertically.

<VStack gap="gap-[2vh]" align="items-start">
  <Title />
  <Description />
  <Actions />
</VStack>

HStack / HStackFull

Horizontal stack (flex-row) for laying out items side-by-side.

<HStack gap="gap-[1.5vh]" className="items-center">
  <Icon />
  <Text>Label</Text>
</HStack>

Color System

NEVER use direct Tailwind color classes like bg-blue-500 or text-red-600. ALWAYS use semantic color tokens that automatically adapt to light/dark themes.

Semantic Color Tokens

Background Colors

// ✅ CORRECT
<Box className="bg-background text-foreground">
  <div className="bg-card text-card-foreground p-[2vh] rounded-xl">
    Card content
  </div>
</Box>

Primary Semantic Colors

  • bg-background / text-background - Page background
  • bg-foreground / text-foreground - Primary text
  • bg-primary / text-primary - Primary UI elements
  • bg-secondary / text-secondary - Secondary UI
  • bg-accent / text-accent - Accent containers

Typography System

This template uses a sophisticated mathematical typography system that scales consistently across ALL screen sizes using CSS variables and ratios. NEVER use arbitrary Tailwind text sizes like text-base, text-lg etc.

Text Size Classes

Always use these custom text size classes:

text-2xs    // Smallest text
text-xs     // Extra small
text-sm     // Small
text-default // Body text (default)
text-lg     // Large
text-xl     // Extra large
text-2xl    // 2x large
text-3xl    // 3x large
// ... continues through text-17xl

Spacing and Layout

Spacing Philosophy

  • Viewport Units First: Use vh and vw for spacing that scales with screen size
  • Tailwind Spacing Second: Use Tailwind's spacing scale for component-level spacing
  • Responsive Variants: Apply different spacing at breakpoints

Viewport-Based Spacing

// ✅ PREFERRED for page-level spacing
<VStackFull className="py-[8vh] px-[4vh] gap-[3vh]">
  <Section className="mb-[6vh]" />
  <Section className="mb-[6vh]" />
</VStackFull>

Responsive Design

The template supports extensive breakpoints from mobile to ultra-wide displays:

Breakpoint System

BASE    360px   (Mobile portrait)
SM      640px   (Mobile landscape)
MD      768px   (Tablet portrait)
LG      1024px  (Tablet landscape)
XL      1280px  (Desktop)
2XL     1536px  (Large desktop)
3XL     1920px  (Full HD)
4XL     2240px  (Ultrawide)
5XL     2560px  (2K)
6XL     2880px  (Retina 5K)
7XL     3840px  (4K)

Button System

Use the pre-built button components from ~/components/basic-ui/customButtons. These handle all theming, sizing, states, and accessibility automatically.

Button Variants

import {
  DefaultButton,
  DestructiveButton,
  OutlineButton,
  SecondaryButton,
  GhostButton,
  LinkButton,
} from "~/components/basic-ui/customButtons";

Best Practices

Component Creation Checklist

  • ✅ Use building blocks from ~/components/basic-ui/building-blocks.tsx
  • ✅ Use semantic color tokens (never direct Tailwind colors)
  • ✅ Use custom typography classes (text-default, text-lg, etc.)
  • ✅ Use viewport units for spacing (vh, vw)
  • ✅ Design mobile-first, enhance for larger screens
  • ✅ Test at multiple breakpoints using /dev/responsiveness
  • ✅ Verify dark mode support
  • ✅ Use appropriate button components
  • ✅ Add proper accessibility attributes
  • ✅ Keep commented code intact (per user rules)

Quick Reference

Import Patterns

// Building blocks
import {
  Box, Flex, FlexFull, HStack, HStackFull,
  VStack, VStackFull, Center, CenterFull,
  Container, ResponsiveGrid, Text, Transition,
} from "~/components/basic-ui/building-blocks";

Class Name Quick Reference

Colors (always semantic):

bg-background, bg-foreground, bg-primary, bg-secondary, bg-accent, bg-card, bg-muted, bg-destructive, bg-highlight

Typography (never use Tailwind defaults):

text-2xs, text-xs, text-sm, text-default, text-lg, text-xl, text-2xl, text-3xl, text-4xl ... text-17xl

Spacing (viewport units preferred):

p-[2vh], py-[4vh], px-[3vh], gap-[2vh], gap-[3vh], gap-[4vh]

Conclusion

This styling system is designed to create fully responsive, accessible, theme-aware applications that scale beautifully from mobile phones to ultra-wide displays. By following these guidelines and using the provided building blocks, you ensure consistency, maintainability, and exceptional user experience across all devices.

Remember:

  • • Building blocks first
  • • Semantic colors always
  • • Viewport units preferred
  • • Mobile-first responsive
  • • Test across breakpoints
  • • Verify dark mode

Happy building! 🚀