Skip to content

CLAUDE.md

Latest commit

 

History

History
364 lines (292 loc) · 13.9 KB

CLAUDE.md

File metadata and controls

364 lines (292 loc) · 13.9 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Build and Development

  • npm run dev - Start development server with live CSS rebuild

    • Runs Tailwind CSS in watch mode
    • Starts live-server on port 3000
    • Opens /src/index.html automatically

  • npm run build - Production build

    • Builds CSS from src/input.css to src/output.css
    • Uses Tailwind CSS to process utility classes

  • npm run serve - Development server only

    • Runs live-server without CSS rebuild
    • Useful when focusing on HTML changes

Deployment

  • npm run deploy - Deploy to GitHub Pages (LOCAL deployment)
    • Builds CSS and deploys to gh-pages branch
    • ALWAYS use this command for deployment (GitHub Actions has billing issues)
    • Triggers GitHub's built-in Pages deployment automatically

Testing and Linting

  • No test framework is currently configured
  • No linting tools are set up
  • Consider implementing these for code quality

Architecture Overview

Project Structure

This is a trauma-informed UI component library built using:

  • Atomic Design methodology - Components organized as atoms, molecules, organisms, pages, and templates
  • Static HTML/CSS - No JavaScript framework, pure HTML with Tailwind CSS
  • Tailwind CSS - Utility-first CSS with extensive customization for trauma-informed design

Component Organization

src/components/
├── atoms/        # Basic building blocks (buttons, typography, form elements)
├── molecules/    # Simple combinations of atoms (planned)
├── organisms/    # Complex UI components (planned)
├── pages/        # Page-specific compositions (planned)
└── templates/    # Page layout structures

Design System

Color Palette

The project uses a mineral-inspired color system:

  • Azurite Blue (#284251) - Primary headers, navigation
  • Chrysocolla Green (#264c52) - CTAs, success states
  • Sunstone Orange (#ce7755) - Warnings, special actions
  • Rhodochrosite Rose (#d4a18c) - Emergency exits, emphasis
  • Selenite White (#f6f0e9) - Primary background

Typography

  • Playfair Display Black - Headlines (serif)
  • Montserrat - Body text and UI elements (sans-serif)
  • Responsive type scale with mobile, tablet, and desktop sizes

Spacing System

Based on 8px grid: xs (4px), sm (8px), md (16px), lg (24px), xl (32px), 2xl (48px)

Trauma-Informed Design Principles

  1. Safety & Predictability - Consistent patterns, gentle transitions (300ms), calming colors
  2. User Control - Content warnings, format alternatives, clear exit options
  3. Clear Communication - Supportive microcopy, non-pressuring language
  4. Emotional Support - Break reminders, grounding exercises (planned)
  5. Spaciousness - Ample white space, rounded corners, visual breathing room

Key Conventions

  • Mobile-first responsive design - All components scale from 320px to desktop
  • Semantic HTML with proper ARIA labels for accessibility
  • BEM-like class naming using Tailwind utilities
  • Consistent hover states with 300ms transitions
  • Touch-friendly targets (minimum 44px on mobile)

Current Implementation Status

  • Atoms: Actively developed (buttons, typography, colors, forms, status indicators)
  • Molecules: Structure exists, components marked "Coming Soon"
  • Organisms: Structure exists, components marked "Coming Soon"
  • Templates: Basic page structure template available

Icon System

SVG icons organized by category in /src/assets/icons/:

  • Accessibility, Content & Learning, Emotional Support, Forms, Navigation, Safety & Support, etc.
  • Designed to be scalable (16px-64px) and trauma-appropriate

Important Notes

  • No external dependencies beyond Tailwind CSS
  • All components are static HTML - no JavaScript interactivity yet
  • Focus is on establishing design patterns and visual language
  • Emergency Exit button is a core trauma-informed feature present on all pages

Product Requirements Document

IMPORTANT: The authoritative guide for building this system is: /uiui/PRD-Trauma-Informed-Interface-Design-System.md

This PRD contains:

  • Implementation phases (1-5) with specific deliverables
  • Feature specifications with acceptance criteria
  • User flows with Mermaid diagrams
  • Database schema for all entities
  • Technical architecture and directory structure
  • Component conversion guide (uiui → Laravel Blade)
  • Success metrics and targets

Always consult the PRD before implementing any feature.

Laravel Project: Trauma-Informed Interface Design System

Tech Stack

  • Laravel 12 - Backend framework
  • Livewire - Reactive UI components (when needed)
  • Alpine.js - Required for all JavaScript interactivity
  • Tailwind CSS v3 - Styling (use design tokens from this UI library)

Project Workspace

  • Laravel Project: /Users/abayomi/Herd/Trauma-Informed-Interface-Design-System
  • UI Knowledge Base: This repository (uiui) serves as the design system reference

Development Workflow

Before Creating Components

  1. Read the design system documentation in this repository
  2. Use design tokens: typography, colors, spacing from tailwind.config.js
  3. Check existing components in src/components/ (atoms, molecules, organisms)
  4. Reuse and adapt existing component patterns

Frontend Development

  • Use Tailwind CSS classes from this design system
  • Implement Alpine.js for client-side interactivity
  • Use Livewire for server-rendered reactive components
  • Follow trauma-informed design principles

Backend Development

  • Laravel 12 with Eloquent ORM
  • RESTful API design
  • Built-in authentication/authorization
  • Proper validation and error handling

System Roles

Full-Stack Software Engineer

When implementing features:

  1. Analyze requirements (frontend and backend)
  2. Justify technology choices
  3. Outline component interactions
  4. Provide code with testing/deployment notes

Always reason step-by-step before writing code.

PRD Specialist

For documentation tasks:

  • Create structured PRDs with Mermaid.js diagrams
  • Sections: Problem Statement, Goals, Personas, Features, User Flows, Acceptance Criteria
  • Use Markdown format

DevOps Engineer

For deployment tasks:

  • GitHub for version control
  • Laravel Cloud for deployment
  • CI/CD pipeline configuration
  • Environment variable management

Integration Guidelines

Using This Design System in Laravel

  1. Copy Tailwind configuration from tailwind.config.js
  2. Reference color palette, typography, and spacing tokens
  3. Adapt HTML components to Blade templates
  4. Convert Alpine.js patterns to Livewire where appropriate
  5. Maintain trauma-informed design principles throughout

Component Conversion Pattern

Static HTML (uiui) → Blade Component (Laravel)
Alpine.js → Keep for client-side OR convert to Livewire for server-side
Tailwind classes → Direct copy (ensure config matches)

System Knowledge Base: /uiui/

IMPORTANT: This /uiui/ directory contains ALL the information needed to build a robust Trauma-Informed Interface Design System on Laravel. Always reference this directory when creating components, styling, or implementing features.

Component Inventory

Atoms (11 files) - /src/components/atoms/

Component File Purpose
Buttons buttons.html Emergency exit, primary, secondary, tertiary buttons with states
Forms form-elements.html Inputs, checkboxes, radios, selects with validation
Typography typography.html H1-H6, body, caption with responsive scaling
Colors color.html Complete color system with swatches
Status status-indicators.html Progress bars, badges, status indicators
Layout layout.html Grid systems, spacing, containers
Media media.html Images, video embeds, accessibility
Icons icons.html Icon usage and sizing guidelines
Safe Mode safe-mode-toggle.html Emergency safe space toggle
Foundations design-foundations.html Design system principles

Molecules (10 files) - /src/components/molecules/

Component File Purpose
Alerts alert.html Content warnings, success/error messages
Cards card.html Generic card with variants
Form Groups form-groups.html Labeled inputs, validation groups
Header Nav header-navigation.html Main navigation bar
Footer Nav footer-navigation.html Footer links and structure
Navigation navigation-components.html Breadcrumbs, pagination, menus
Tags tag-group.html Tag and badge systems
Media Controls media-controls.html Play/pause, volume, transcripts
Text Groups text-group.html Text combinations, quotes, info boxes

Organisms (19 files) - /src/components/organisms/

Component File Purpose
Course Cards course-card-system.html Course overview, progress, enrollment
Blog Cards blog-card-system.html Article previews, author info
Hero Section hero-section.html Large banner with CTA
Registration course-registration-system.html Multi-step enrollment
Newsletter newsletter-subscription-section.html Email signup
Payment payment-section.html Payment form section
Toolkit Cards toolkit-card-system.html Resource/download cards
Case Studies case-study-card.html Project showcases
Settings settings-system.html User preferences interface

Pages (6 files) - /src/components/pages/

  • dashboard-page-component.html - User dashboard layout
  • user-flow.html through user-flow-v-4.html - Complete user journeys

Templates (5 files) - /src/components/templates/

  • home-page.html - Landing page template
  • sign-in.html - Login page
  • multi-step-account-creation.html - Registration wizard
  • create-password.html - Password setup
  • password-reset.html - Recovery flow

Design Token Reference

Colors (from tailwind.config.js)

Azurite Blue:       #284251 (headers, navigation, trust)
Chrysocolla Green:  #264c52 (CTAs, success, encouragement)
Sunstone Orange:    #ce7755 (warnings, special actions)
Rhodochrosite Rose: #d4a18c (emergency, sensitivity)
Selenite White:     #f6f0e9 (backgrounds, calm)
Grey:               #454545 (text, borders)

Typography

Headlines: Playfair Display Black (serif)
Body:      Montserrat (sans-serif)

Desktop:   h1=48px, h2=36px, h3=24px, h4=20px
Tablet:    h1=40px, h2=32px, h3=22px, h4=18px
Mobile:    h1=32px, h2=28px, h3=20px, h4=18px
Body:      16px/24px line-height

Spacing (8px grid)

xs=4px, sm=8px, md=16px, lg=24px, xl=32px, 2xl=48px

Border Radius

sm=4px, DEFAULT=6px, md=8px, lg=12px, xl=16px, full=9999px

Alpine.js Components (/src/js/button-components.js)

// Emergency Exit - immediate redirect
emergencyExit({ exitUrl: 'https://google.com', position: 'bottom-right' })

// Primary Button - with loading/success/error states
primaryButton({ label: 'Continue', tooltip: 'Click to proceed' })

// Secondary Button - alternative actions
secondaryButton({ label: 'Browse Options' })

// Tertiary Button - optional actions with confirmation
tertiaryButton({ label: 'Learn More', requiresConfirmation: true })

Icon Library (/src/assets/icons/)

56 SVG icons in 11 categories:

  • accessibility/ - accessibility, captions, contrast, magnify, volume
  • content-and-learning/ - audio, bookmark, document, download, play, pause, video
  • emotional-support/ - breathing, comfort, meditation, mindfulness, wellness
  • forms-element/ - cancel, edit, filter, refresh, save, search, sort
  • learning-management/ - certificate, course, graduation, lesson, module, quiz
  • progress-and-status/ - calendar, check, clock, star, trophy
  • safety-and-support/ - alert, chat, exit, heart, phone, shield, support, warning

Key Documentation Files

Document Purpose
COMPONENTS.md Complete component reference
button-system-doc/ Button component specifications
accessibility-features-reference.md WCAG compliance guide
trauma-informed-ui-library-revised.md Design principles deep-dive
tailwind.config.js All design tokens

File Path Quick Reference

/uiui/
├── src/
│   ├── index.html                    # Main entry point
│   ├── output.css                    # Compiled Tailwind CSS
│   ├── js/button-components.js       # Alpine.js components
│   ├── assets/icons/                 # 56 SVG icons
│   └── components/
│       ├── atoms/                    # 11 base components
│       ├── molecules/                # 10 compound components
│       ├── organisms/                # 19 complex components
│       ├── pages/                    # 6 page examples
│       └── templates/                # 5 page templates
├── tailwind.config.js                # Design tokens
├── COMPONENTS.md                     # Component docs
└── button-system-doc/                # Button specs

Mandatory Workflow for Laravel Development

  1. Before creating ANY component:

    • Check if it exists in /uiui/src/components/
    • Read the HTML implementation
    • Copy Tailwind classes exactly
    • Adapt Alpine.js patterns for Livewire if needed

  2. For styling:

    • Use design tokens from tailwind.config.js
    • Never invent new colors or spacing values
    • Follow the 8px grid system

  3. For interactivity:

    • Reference button-components.js for Alpine.js patterns
    • Maintain trauma-informed states (loading, success, error)
    • Always include accessible ARIA attributes

  4. For accessibility:

    • Follow patterns in accessibility-features-reference.md
    • Maintain 44px minimum touch targets
    • Respect prefers-reduced-motion
    • Include proper focus states
  • Always read prd before implementation