Plings Design System Implementation Guide

Overview

This guide explains how the Plings design system is implemented using Tailwind CSS, CSS custom properties, and React components.

Color System Implementation

CSS Custom Properties (HSL Format)

Located in src/index.css:

:root {
  --primary: 174 100% 29%;      /* #009688 */
  --secondary: 88 50% 53%;      /* #8BC34A */
  --accent: 65 55% 77%;         /* #DCE775 */
  --background: 0 0% 100%;      /* #FFFFFF */
  --foreground: 210 15% 23%;    /* #37474F */
}

Tailwind Color Configuration

Located in tailwind.config.ts:

colors: {
  primary: {
    DEFAULT: '#009688',
    light: '#8BC34A',
    dark: '#00695C',
    foreground: '#ffffff'
  },
  secondary: {
    DEFAULT: '#8BC34A',
    foreground: '#ffffff'
  },
  // ... other colors
}

Usage in Components

Using Tailwind Classes

// Primary button
<Button className="bg-primary text-primary-foreground">
  Primary Action
</Button>

// Secondary button
<Button className="bg-secondary text-secondary-foreground">
  Secondary Action
</Button>

// Text colors
<h1 className="text-foreground">Main Heading</h1>
<p className="text-muted-foreground">Subtitle text</p>

Using CSS Custom Properties

// Direct HSL usage
<div style={{ backgroundColor: 'hsl(var(--primary))' }}>
  Custom styled element
</div>

// With opacity
<div style={{ backgroundColor: 'hsl(var(--primary) / 0.1)' }}>
  Semi-transparent background
</div>

Typography Implementation

Font Loading

Poppins font is loaded via Google Fonts in index.html:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700&display=swap" rel="stylesheet">

Tailwind Configuration

fontFamily: {
  'poppins': ['Poppins', 'sans-serif'],
  'sans': ['Poppins', 'sans-serif'],
}

Usage Examples

// Default font (Poppins applied globally)
<p className="text-base">Regular text</p>

// Specific font weights
<h1 className="font-bold text-2xl">Bold heading</h1>
<p className="font-medium">Medium weight text</p>
<span className="font-light text-sm">Light subtitle</span>

// Font sizes
<h1 className="text-4xl">Large heading</h1>
<h2 className="text-2xl">Medium heading</h2>
<p className="text-base">Body text</p>
<small className="text-sm">Small text</small>

Component Styling Examples

Search Interface Components

<div className="max-w-2xl mx-auto">
  <div className="relative">
    <input
      type="text"
      placeholder="Search objects, classes, or collections..."
      className="w-full pl-12 pr-4 py-3 text-lg border border-border rounded-lg 
                 focus:ring-2 focus:ring-primary focus:border-transparent
                 bg-background text-foreground"
    />
    <Search className="absolute left-4 top-1/2 transform -translate-y-1/2 
                       text-muted-foreground w-5 h-5" />
  </div>
</div>

Search Results Card

<div className="bg-card border border-border rounded-lg p-6 hover:shadow-md 
                transition-shadow cursor-pointer">
  <div className="flex items-start justify-between">
    <div className="flex-1">
      <h3 className="font-semibold text-lg text-foreground mb-2">
        Object Title
      </h3>
      <p className="text-muted-foreground text-sm mb-3">
        Object description...
      </p>
      <span className="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs 
                       font-medium bg-primary/10 text-primary">
        Object Type
      </span>
    </div>
  </div>
</div>

Button Variants

Primary Button

<Button className="bg-primary hover:bg-primary-dark text-primary-foreground 
                   font-medium px-6 py-2 rounded-lg transition-colors">
  Primary Action
</Button>

Outline Button

<Button className="border border-primary text-primary hover:bg-primary 
                   hover:text-primary-foreground font-medium px-6 py-2 
                   rounded-lg transition-colors">
  Secondary Action
</Button>

<header className="bg-background border-b border-border">
  <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
    <div className="flex justify-between items-center h-16">
      <a href="/" className="flex items-center">
        <img 
          src="/static/logos/plings-logo.png" 
          alt="Plings Logo" 
          className="h-8 w-auto hover:opacity-80 transition-opacity"
        />
      </a>
      <nav className="flex items-center space-x-4">
        <a href="/about" className="text-foreground hover:text-primary 
                                   transition-colors font-medium">
          Learn more
        </a>
      </nav>
    </div>
  </div>
</header>

Object Status Implementation

Status Colors in Tailwind

status: {
  active: '#10B981',
  'for-sale': '#3B82F6',
  lost: '#F59E0B',
  stolen: '#EF4444',
  broken: '#F97316',
  destructed: '#6B7280'
}

Status Badge Component

const StatusBadge = ({ status }: { status: string }) => {
  const statusColors = {
    active: 'bg-status-active',
    'for-sale': 'bg-status-for-sale',
    lost: 'bg-status-lost',
    stolen: 'bg-status-stolen',
    broken: 'bg-status-broken',
    destructed: 'bg-status-destructed'
  };

  return (
    <span className={`inline-flex items-center px-2.5 py-0.5 rounded-full 
                      text-xs font-medium text-white ${statusColors[status]}`}>
      {status.replace('-', ' ').toUpperCase()}
    </span>
  );
};

Responsive Design Implementation

Mobile-First Approach

// Container with responsive padding
<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
  
  // Responsive grid
  <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
    
    // Responsive text sizes
    <h1 className="text-2xl md:text-4xl lg:text-6xl font-bold">
      Responsive Heading
    </h1>
    
    // Responsive spacing
    <div className="py-8 md:py-16 lg:py-20">
      Content with responsive spacing
    </div>
  </div>
</div>

Breakpoint Usage

  • sm: - Small devices (640px+)
  • md: - Medium devices (768px+)
  • lg: - Large devices (1024px+)
  • xl: - Extra large devices (1280px+)
  • 2xl: - 2X large devices (1536px+)

Dark Mode Support

CSS Custom Properties for Dark Mode

.dark {
  --background: 210 15% 5%;
  --foreground: 0 0% 98%;
  --primary: 174 100% 29%;
  --muted: 210 15% 15%;
  --border: 210 15% 15%;
}

Component Implementation

// Components automatically adapt to dark mode through CSS custom properties
<div className="bg-background text-foreground border border-border">
  Content that adapts to light/dark mode
</div>

Performance Considerations

CSS Custom Properties Benefits

  • Efficient runtime theme switching
  • Reduced CSS bundle size
  • Better browser caching
  • Consistent color management

Tailwind Optimization

  • Purge unused classes in production
  • Use semantic color names
  • Leverage Tailwind’s JIT compiler
  • Minimize custom CSS

Best Practices

Color Usage

  1. Use semantic color names (primary, secondary, accent)
  2. Maintain consistent contrast ratios
  3. Test with color blindness simulators
  4. Use status colors meaningfully

Typography

  1. Stick to the established scale
  2. Use appropriate font weights
  3. Maintain readable line heights
  4. Consider loading performance

Components

  1. Use existing shadcn/ui components when possible
  2. Extend rather than override component styles
  3. Maintain consistent spacing patterns
  4. Test across different screen sizes

Accessibility

  1. Ensure sufficient color contrast
  2. Provide focus indicators
  3. Use semantic HTML elements
  4. Test with screen readers