@psp-asia/layout - PSP Layout & Debug Tools

Complete layout and debugging system for PSP development with TailwindCSS integration.

Package Contents

Layout System (grid.css)

• Rack: CSS Grid container with responsive track system
• Rail: Horizontal scroll container with fixed-width columns

Debug Tools (debug.css, debug.js)

• Visual debugging overlay for grid layouts
• Territory lines and viewport controls
• Development-only utilities

Installation

npm install @psp-asia/layout

Usage

Basic Layout Import

@import "@psp-asia/layout/grid.css";

Development with Debug Tools

<!-- CSS -->
<link rel="stylesheet" href="/npm/@psp-asia/layout/grid.css">
<link rel="stylesheet" href="/npm/@psp-asia/layout/debug.css">

<!-- JS -->
<script src="/npm/@psp-asia/layout/debug.js"></script>

Rack System (CSS Grid)

Responsive Track System

• sm (default): 4 tracks
• md (48rem+): 14 tracks
• lg (64rem+): 24 tracks

Column Classes

.col-1 through .col-12  /* Responsive column spans */
.col-start-N            /* Grid positioning */

Examples

<div class="rack">
  <div class="col-6">Half width</div>
  <div class="col-6">Half width</div>
</div>

<div class="rack">
  <div class="col-start-2 col-10">Centered content</div>
</div>

Rail System (Horizontal Scroll)

Fixed Width Columns

.col-1  → 16rem (256px)
.col-2  → 20rem (320px)
.col-3  → 24rem (384px)
/* ... up to .col-12 → 100% */

Examples

<div class="rail">
  <div class="col-3">Card 1</div>
  <div class="col-3">Card 2</div>
  <div class="col-3">Card 3</div>
</div>

Debug Tools

Features

• Visual grid overlay
• Territory line indicators
• Viewport size display
• Development-only activation

Activation

The debug tools activate automatically in development environments and provide visual feedback for layout debugging.

File Structure

@psp-asia/layout/
├── grid.css    # Main layout system
├── debug.css   # Debug visual styles
└── debug.js    # Debug functionality

Browser Support

• Modern browsers with CSS Grid support
• Flexbox fallback for older browsers
• Progressive enhancement approach

@psp-asia/layout System Guide

Core Understanding

The @psp-asia/layout system uses semantic grid classes that automatically adapt to screen sizes. Never use responsive prefixes like lg:, md:, sm: - the system handles breakpoints internally.

Container Types

1. Rack Container

• Purpose: Responsive grid that wraps columns to new lines
• Behavior: Automatically adjusts column spans based on screen size
• Usage: Use for main content layouts, sections, cards

<div class="rack">
  <div class="col-6">Half width content</div>
  <div class="col-6">Other half content</div>
</div>

2. Rail Container

• Purpose: Horizontal scrolling container
• Behavior: Columns scroll horizontally, never wrap
• Usage: Use for image galleries, carousels, timeline views

<div class="rail">
  <div class="col-3">Card 1</div>
  <div class="col-3">Card 2</div>
  <div class="col-3">Card 3</div>
</div>

Column System

Basic Columns (col-1 to col-12)

• col-1: Smallest column (1/12 semantic width)
• col-6: Half width (6/12 semantic width)
• col-12: Full width (12/12 semantic width)

How it actually works:

• Mobile (sm): 4 physical grid tracks
  • col-1, col-2 = 2 tracks each
  • col-3 to col-12 = 4 tracks (full width)
• Tablet (md): 14 physical grid tracks
  • col-1 to col-4 = 6 tracks each
  • col-5, col-6 = 10 tracks each
  • col-7 to col-12 = 14 tracks (full width)
• Desktop (lg): 24 physical grid tracks
  • col-1 = 2 tracks, col-2 = 4 tracks, etc.
  • col-12 = 24 tracks (full width)

Positioning with Offsets

Use offset-N + col-M together for positioning:

<div class="rack">
  <div class="offset-2 col-8">Centered content (2 + 8 + 2 = 12)</div>
  <div class="offset-3 col-6">Smaller centered (3 + 6 + 3 = 12)</div>
</div>

Common Patterns

Full Width Section

<div class="rack">
  <div class="col-12">
    <!-- Full width content -->
  </div>
</div>

Two Column Layout

<div class="rack">
  <div class="col-8">Main content</div>
  <div class="col-4">Sidebar</div>
</div>

Three Column Layout

<div class="rack">
  <div class="col-4">Column 1</div>
  <div class="col-4">Column 2</div>
  <div class="col-4">Column 3</div>
</div>

Centered Content

<div class="rack">
  <div class="offset-3 col-6">Centered content</div>
</div>

Card Grid

<div class="rack">
  <div class="col-3">Card 1</div>
  <div class="col-3">Card 2</div>
  <div class="col-3">Card 3</div>
  <div class="col-3">Card 4</div>
</div>

Horizontal Scrolling Gallery

<div class="rail">
  <div class="col-3">Image 1</div>
  <div class="col-3">Image 2</div>
  <div class="col-3">Image 3</div>
  <div class="col-3">Image 4</div>
  <div class="col-3">Image 5</div>
</div>

Critical Rules

1. NO responsive prefixes: Never use lg:col-6, md:col-4, etc.
2. Container required: Always wrap col-* inside rack or rail
3. Semantic sizing: Think in terms of 12-column layout, system handles physical tracks
4. Offset for positioning: Use offset-N for gaps and centering
5. Rail for horizontal: Use rail only when you want horizontal scrolling

Ruby Helpers (Optional)

If using Ruby/ERB, you can create helpers:

def rack_container(&block)
  content = capture(&block) if block_given?
  "<div class=\"rack\">#{content}</div>".html_safe
end

def col(size, offset = nil, &block)
  content = capture(&block) if block_given?
  css_classes = ["col-#{size}"]
  css_classes << "offset-#{offset}" if offset
  "<div class=\"#{css_classes.join(' ')}\">#{content}</div>".html_safe
end

Usage:

<%= rack_container do %>
  <%= col(6) do %>Content 1<% end %>
  <%= col(6) do %>Content 2<% end %>
<% end %>

Anti-Patterns (Don't Do This)

❌ Using responsive prefixes

<!-- WRONG -->
<div class="col-12 md:col-6 lg:col-4">Content</div>

❌ Missing container

<!-- WRONG -->
<div class="col-6">Content</div>

❌ Wrong container for purpose

<!-- WRONG: Using rail for normal layout -->
<div class="rail">
  <div class="col-12">Full width content</div>
</div>

✅ Correct Usage

<!-- CORRECT -->
<div class="rack">
  <div class="col-6">Content</div>
</div>

The system is designed to be simple: think semantically about your 12-column layout, use rack for normal layouts and rail for horizontal scrolling, and let the system handle all responsive behavior automatically.