Design System - joinruach/JoinRuach GitHub Wiki

Design System

Overview

The Ruach Studios design system is the visual and experiential language that unifies all our digital and physical touchpoints. It's built on principles of clarity, beauty, and purpose.

We design for:

  • Readability — Information should be easy to consume
  • Accessibility — Everyone should be able to engage
  • Emotion — Design should evoke meaning, not just function
  • Consistency — Patterns should feel familiar across platforms

Brand Identity

Mission-Driven Aesthetics

Our visual language reflects who we are:

  • Grounded, not flashy — Substance over style
  • Modern, not trendy — Timeless, not temporary
  • Warm, not cold — Human, not robotic
  • Bold, not loud — Confident, not obnoxious

Color Palette

Primary Colors

Ruach Blue — Identity & Trust

  • Primary: #1A56DB (rgb(26, 86, 219))
  • Light: #3F83F8 (rgb(63, 131, 248))
  • Dark: #1E429F (rgb(30, 66, 159))

Usage:

  • Primary CTAs (Call-to-Actions)
  • Links and interactive elements
  • Brand accents

Ruach Charcoal — Grounding & Depth

  • Primary: #1F2937 (rgb(31, 41, 55))
  • Light: #374151 (rgb(55, 65, 81))
  • Dark: #111827 (rgb(17, 24, 39))

Usage:

  • Body text
  • Headers
  • Backgrounds

Ruach Cream — Warmth & Light

  • Primary: #FFF8E7 (rgb(255, 248, 231))
  • Light: #FFFCF5 (rgb(255, 252, 245))
  • Dark: #F9F3E3 (rgb(249, 243, 227))

Usage:

  • Backgrounds (light mode)
  • Card backgrounds
  • Section dividers

Secondary Colors

Ember Orange — Energy & Action

  • Primary: #F97316 (rgb(249, 115, 22))
  • Usage: Highlights, alerts, secondary CTAs

Sage Green — Growth & Renewal

  • Primary: #10B981 (rgb(16, 185, 129))
  • Usage: Success states, positive feedback

Stone Gray — Neutrality & Balance

  • Primary: #6B7280 (rgb(107, 114, 128))
  • Usage: Muted text, borders, disabled states

System Colors

  • Success: #10B981 (Green)
  • Warning: #F59E0B (Amber)
  • Error: #EF4444 (Red)
  • Info: #3B82F6 (Blue)

Typography

Font Families

Headings: Inter (sans-serif)

  • Modern, clean, highly readable
  • Available via Google Fonts
  • Font weights: 400 (Regular), 600 (Semi-Bold), 700 (Bold)

Body: Inter (sans-serif)

  • Same as headings for consistency
  • Font weight: 400 (Regular)

Code: Fira Code or JetBrains Mono (monospace)

  • For technical documentation and code snippets

Type Scale

Element Size (rem) Size (px) Line Height Weight
Display 4.5 72 1.1 700 (Bold)
H1 3.0 48 1.2 700 (Bold)
H2 2.25 36 1.2 700 (Bold)
H3 1.875 30 1.3 600
H4 1.5 24 1.4 600
H5 1.25 20 1.4 600
H6 1.125 18 1.4 600
Body Large 1.125 18 1.6 400
Body 1.0 16 1.6 400
Body Small 0.875 14 1.5 400
Caption 0.75 12 1.4 400

Usage Examples

/* Display */
font-size: 4.5rem;
line-height: 1.1;
font-weight: 700;

/* Heading 1 */
font-size: 3rem;
line-height: 1.2;
font-weight: 700;

/* Body Text */
font-size: 1rem;
line-height: 1.6;
font-weight: 400;

Spacing

We use an 8px base unit for consistent spacing across the design system.

Spacing Scale

Token Value (rem) Value (px) Usage
xs 0.25 4 Tight spacing (icons, badges)
sm 0.5 8 Small gaps (inline elements)
md 1.0 16 Default spacing (buttons, cards)
lg 1.5 24 Larger gaps (sections)
xl 2.0 32 Section padding
2xl 3.0 48 Large sections
3xl 4.0 64 Hero sections

Layout

Grid System

We use a 12-column grid with responsive breakpoints.

Breakpoints

Size Min Width Max Width Columns
xs 0px 639px 4
sm 640px 767px 8
md 768px 1023px 12
lg 1024px 1279px 12
xl 1280px 1535px 12
2xl 1536px+ — 12

Container Max-Widths

  • xs: 100%
  • sm: 640px
  • md: 768px
  • lg: 1024px
  • xl: 1280px
  • 2xl: 1536px

Components

Buttons

Primary Button

  • Background: Ruach Blue (#1A56DB)
  • Text: White
  • Padding: 12px 24px
  • Border Radius: 8px
  • Font Weight: 600
  • Hover: Darken by 10%

Secondary Button

  • Background: Transparent
  • Border: 2px solid Ruach Blue
  • Text: Ruach Blue
  • Padding: 12px 24px
  • Border Radius: 8px
  • Hover: Fill with Ruach Blue, text becomes white

Tertiary Button

  • Background: Stone Gray (#6B7280)
  • Text: White
  • Padding: 12px 24px
  • Border Radius: 8px
  • Hover: Darken by 10%

Input Fields

  • Height: 48px
  • Padding: 12px 16px
  • Border: 1px solid #D1D5DB
  • Border Radius: 8px
  • Font Size: 16px
  • Focus State: Border color changes to Ruach Blue, add 2px shadow

Cards

  • Background: White (light mode) or Charcoal (dark mode)
  • Border: 1px solid #E5E7EB
  • Border Radius: 12px
  • Padding: 24px
  • Shadow: 0 1px 3px rgba(0,0,0,0.1)
  • Hover: Lift with shadow (0 4px 6px rgba(0,0,0,0.1))

Navigation

  • Height: 64px
  • Background: White with slight transparency
  • Sticky: Yes (stays at top on scroll)
  • Logo: Left-aligned
  • Links: Right-aligned, horizontal spacing of 32px

Footer

  • Background: Ruach Charcoal (#1F2937)
  • Text: Stone Gray (#9CA3AF)
  • Links: White on hover
  • Padding: 64px 24px
  • Layout: Multi-column (responsive)

Iconography

Icon Set

We use Lucide Icons (open-source, consistent, and well-maintained).

Icon Sizes

  • Small: 16px
  • Medium: 24px (default)
  • Large: 32px

Icon Colors

  • Primary: Ruach Blue
  • Secondary: Stone Gray
  • Muted: Light Gray

Usage

import { Home, User, Settings } from 'lucide-react';

<Home size={24} color="#1A56DB" />

Imagery

Photography Style

  • Natural lighting — Avoid overly staged or artificial looks
  • Human-centered — People over objects
  • Authentic moments — Real emotions, not stock photo smiles
  • High contrast — Bold shadows and light

Aspect Ratios

  • Hero images: 16:9
  • Card images: 4:3
  • Profile images: 1:1 (square)
  • Banner images: 21:9 (ultra-wide)

Image Optimization

  • Format: WebP (with JPG fallback)
  • Compression: 80% quality
  • Lazy loading: Yes (for below-the-fold images)

Motion & Animation

Principles

  • Purposeful — Animations guide attention, don't distract
  • Subtle — Smooth and refined, not flashy
  • Fast — Animations should feel snappy (200-300ms)

Easing Functions

  • Ease-in: cubic-bezier(0.4, 0, 1, 1) — Starts slow, ends fast
  • Ease-out: cubic-bezier(0, 0, 0.2, 1) — Starts fast, ends slow (default)
  • Ease-in-out: cubic-bezier(0.4, 0, 0.2, 1) — Smooth both ways

Common Animations

Fade In

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

Slide Up

@keyframes slideUp {
  from { transform: translateY(20px); opacity: 0; }
  to { transform: translateY(0); opacity: 1; }
}

Button Hover

button {
  transition: all 200ms ease-out;
}

button:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}

Accessibility

Color Contrast

All text must meet WCAG AA standards (4.5:1 contrast ratio for normal text, 3:1 for large text).

Tools to check:

Focus States

All interactive elements must have visible focus states for keyboard navigation.

button:focus-visible {
  outline: 2px solid #1A56DB;
  outline-offset: 2px;
}

Alt Text for Images

Every image must have descriptive alt text.

<img src="hero.jpg" alt="A man standing on a mountain at sunrise, arms raised in victory" />

Design Tokens (Tailwind Config)

module.exports = {
  theme: {
    colors: {
      ruach: {
        blue: '#1A56DB',
        blueLight: '#3F83F8',
        blueDark: '#1E429F',
        charcoal: '#1F2937',
        cream: '#FFF8E7',
        ember: '#F97316',
        sage: '#10B981',
        stone: '#6B7280',
      },
    },
    fontFamily: {
      sans: ['Inter', 'sans-serif'],
      mono: ['Fira Code', 'monospace'],
    },
    spacing: {
      xs: '0.25rem', // 4px
      sm: '0.5rem',  // 8px
      md: '1rem',    // 16px
      lg: '1.5rem',  // 24px
      xl: '2rem',    // 32px
      '2xl': '3rem', // 48px
      '3xl': '4rem', // 64px
    },
  },
};

Resources

Figma Files

Tools

  • Figma — Design and prototyping
  • Tailwind CSS — Utility-first CSS framework
  • Lucide Icons — Icon library

Questions?

If you have questions about the design system:

"The Lord has filled him with the Spirit of God, with skill, with intelligence, with knowledge, and with all craftsmanship." — Exodus 35:31