Blog App Design System & Guidelines

🎨 Design Philosophy

This blog application follows a modern, clean, and accessible design approach using Tailwind CSS. The design emphasizes readability, user-friendly interactions, and responsive layouts.

📋 Design Principles

1. Color Palette

Primary: Blue (

bg-blue-600

hover:bg-blue-700

text-blue-600

)

Neutral: Gray scale (

text-gray-900

text-gray-600

text-gray-300

border-gray-200

)

Background: White (
```
bg-white
```
) with subtle shadows
Accent: Use blue for CTAs, links, and interactive elements

2. Typography Scale

Main Title:
```
text-4xl font-bold text-gray-900
```
Section Headers:
```
text-xl font-semibold text-gray-900
```
Body Text:
```
text-gray-600 text-sm
```
or
```
text-base
```
Captions/Meta:
```
text-sm text-gray-500
```

3. Spacing & Layout

Container:
```
max-w-4xl mx-auto
```
for main content areas

Grid: Responsive grids

grid gap-6 md:grid-cols-2 lg:grid-cols-3

Padding:
```
p-6
```
for card content,
```
px-6 py-3
```
for buttons
Margins:
```
mb-4
```
,
```
mb-6
```
,
```
mb-8
```
for consistent vertical rhythm

🧩 Component Patterns

Primary Button

<%= link_to path, class: "inline-flex items-center px-6 py-3 bg-blue-600 hover:bg-blue-700 text-white font-medium rounded-lg shadow-md hover:shadow-lg transition-all duration-200" do %>
  <!-- SVG Icon (optional) -->
  <svg class="w-5 h-5 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="..."></path>
  </svg>
  Button Text
<% end %>

Card Component

<div class="bg-white rounded-lg shadow-md hover:shadow-xl transition-shadow duration-300 overflow-hidden border border-gray-200">
  <div class="p-6">
    <!-- Card content -->
  </div>
</div>

Page Header Pattern

<div class="max-w-4xl mx-auto">
  <div class="mb-8">
    <h1 class="text-4xl font-bold text-gray-900 mb-4">Page Title</h1>
    <p class="text-lg text-gray-600 mb-6">Page description</p>
    <!-- Primary action button -->
  </div>
</div>

Grid Layout Pattern

<div class="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
  <!-- Grid items -->
</div>

Meta Information Pattern

<div class="flex items-center justify-between text-sm text-gray-500">
  <time datetime="<%= datetime %>" class="flex items-center">
    <svg class="w-4 h-4 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
      <!-- Clock icon -->
    </svg>
    <%= formatted_date %>
  </time>
</div>

🎯 Interactive Elements

Hover States

Cards:

hover:shadow-xl transition-shadow duration-300

Buttons:

hover:bg-blue-700 transition-all duration-200

Links:
```
hover:text-blue-600 transition-colors
```

Focus States

Always maintain accessibility with proper focus indicators

Use

focus:outline-none focus:ring-2 focus:ring-blue-500

when customizing

📱 Responsive Design

Breakpoint Strategy

Mobile First: Base styles for mobile (< 768px)
Tablet:
```
md:
```
prefix for tablet (≥ 768px)
Desktop:
```
lg:
```
prefix for desktop (≥ 1024px)

Grid Responsiveness

Mobile: 1 column (default)
Tablet: 2 columns (
```
md:grid-cols-2
```
)
Desktop: 3 columns (
```
lg:grid-cols-3
```
)

🎪 Icon System

Icon Guidelines

Use Heroicons style SVG icons
Standard sizes:
```
w-4 h-4
```
(small),
```
w-5 h-5
```
(medium),
```
w-6 h-6
```
(large)

Always include

fill="none" stroke="currentColor" viewBox="0 0 24 24"

Common icons to use:
- Plus icon for "Create/Add" actions
- Clock icon for timestamps
- Arrow right for "Read more" links
- Document icon for empty states

🚫 Empty States

Empty State Pattern

<% if collection.empty? %>
  <div class="text-center py-12">
    <svg class="w-16 h-16 mx-auto text-gray-300 mb-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
      <!-- Relevant icon -->
    </svg>
    <h3 class="text-xl font-medium text-gray-900 mb-2">No Items Found</h3>
    <p class="text-gray-600 mb-6">Description of empty state</p>
    <!-- Call to action button -->
  </div>
<% end %>

🌍 Accessibility Guidelines

Requirements

Use semantic HTML elements (
```
<article>
```
,
```
<time>
```
,
```
<main>
```
, etc.)
Include proper ARIA labels where needed
Maintain sufficient color contrast ratios
Ensure keyboard navigation works properly
Add
```
alt
```
attributes to images
Use
```
datetime
```
attributes for time elements

Japanese Text Considerations

Use appropriate Japanese typography
Ensure proper line heights for Japanese characters
Consider reading direction and text flow

🚀 Animation & Transitions

Standard Transitions

Duration:
```
duration-200
```
(fast),
```
duration-300
```
(standard)
Easing: Use default Tailwind easing

Properties:

transition-all

transition-shadow

transition-colors

Hover Effects

Subtle shadow increases on cards
Color changes on interactive elements
Smooth transitions for better UX

📝 Form Styling (Future Reference)

Input Fields

<input class="w-full px-4 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent">

Form Layout

Use consistent spacing with
```
space-y-4
```
or
```
space-y-6
```
Group related fields visually
Provide clear labels and error states

🔧 Implementation Notes

CSS Classes to Consistently Use

Shadows:
```
shadow-md
```
,
```
hover:shadow-xl
```
Rounded corners:
```
rounded-lg
```
for cards, buttons
Text truncation:
```
line-clamp-2
```
,
```
line-clamp-3
```
(ensure Tailwind line-clamp plugin is enabled)
Transitions: Always include appropriate transition classes

Performance Considerations

Use
```
transform
```
and
```
opacity
```
for animations when possible
Minimize layout shifts with consistent sizing
Optimize images with appropriate sizing

🎯 Quick Reference for Common Screens

Index/List Pages

Page header with title, description, and primary action
Responsive grid of cards
Empty state handling
Consistent meta information display

Show/Detail Pages

Clear content hierarchy
Action buttons (edit, delete, back)
Proper typography scale
Related content sections

Forms

Clear field labels
Consistent input styling
Proper error handling
Submit button styling

Clean, minimal design
Clear active states
Mobile-responsive hamburger menu
Consistent brand presence

Remember: Always prioritize user experience, accessibility, and maintainable code when implementing these designs.