🧬 SwS Website - Smarter with Science

Science for communities, by communities

---

🌟 About

The Smarter with Science (SwS) website is the digital home of our community-driven science initiative. Built with a cyberpunk utopian aesthetic, it showcases our projects, connects researchers, and democratizes scientific discovery through beautiful, accessible design.

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm 9+
• Git for version control
• Claude Code (optional, for AI-assisted development)

Installation

# Clone the repository
git clone https://github.com/smarterwithscience/sws-website.git
cd sws-website

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Start development server
npm run dev

# Open browser to http://localhost:4321

📖 Documentation

• SETUP.md - Detailed setup instructions
• CONTRIBUTING.md - How to contribute
• MCP_GUIDE.md - AI agent configuration
• .claude/ - Claude Code context files

🎨 Design System

Our website embodies a cyberpunk utopian aesthetic:

Element	Value	Usage
Primary Color	Purple #9333EA	CTAs, links, emphasis
Secondary Color	Cyan #06B6D4	Accents, highlights
Background	Deep Black #0A0A0A	Main background
Header Font	Orbitron	Futuristic, bold
Body Font	Rajdhani	Clean, technical

📁 Project Structure

sws-website/
├── .claude/            # AI agent context files
├── .github/            # GitHub workflows and templates
├── src/
│   ├── assets/         # Images, styles, fonts
│   ├── components/     # Reusable Astro components
│   ├── content/        # Markdown content (blog, projects, etc.)
│   ├── layouts/        # Page layouts
│   ├── pages/          # Route pages
│   └── utils/          # Utility functions
├── public/             # Static assets
├── scripts/            # Build and utility scripts
├── tests/              # Test files
└── package.json        # Dependencies and scripts

🛠️ Technology Stack

• Framework: Astro v5.x - Static site generator
• Styling: Tailwind CSS v3.x - Utility-first CSS
• Template: AstroWind - Professional template
• Images: GPT-4o (gpt-image-1) - AI-generated imagery
• Testing: Playwright - Visual regression testing
• Deployment: Vercel - Edge deployment
• Content: Markdown with content collections

👥 For Different Contributors

For Developers

# Run tests
npm run test

# Build for production
npm run build

# Preview production build
npm run preview

# Run visual tests
npm run test:visual

For Content Contributors

1. Add Research Article: Create markdown file in src/content/placeholders/blog/
2. Add Project: Create markdown file in src/content/placeholders/projects/
3. Update Text: Edit existing .astro or .md files
4. Add Images: Place in public/images/ with descriptive names

For Designers (Hi Zach! 👋)

Visual Review Process:

1. Run npm run dev to start local server
2. Make design changes (or describe them)
3. Run npm run capture to generate screenshots
4. Review changes in tests/visual/report.html
5. Approve or request adjustments

No coding required! Just describe what you want changed, and our AI agents or developers will implement it.

🤖 AI Agent Development

This project is optimized for AI-assisted development. Context files help agents understand the project:

• CLAUDE.md - Main AI context
• ZACH.md - Visual collaboration context
• contexts/*.md - Technology-specific contexts

Generating New Content

# Generate new project page
npm run generate:project "Project Name"

# Generate research article
npm run generate:research "Article Title"

# Generate hero images
npm run generate:images

🔄 Obsidian Vault Integration

This website lives within the SwS Obsidian vault at /org/website/. Content flows:

Obsidian Vault → Sync Scripts → Website Content → Build → Deploy

Syncing Content

# Pull latest from vault
npm run sync:pull

# Push changes to vault
npm run sync:push

# Full sync
npm run sync

📊 Visual Testing

We use Playwright for visual regression testing:

# Capture current state
npm run test:visual

# View report
open tests/visual/report.html

# Update baselines
npm run test:visual:update

🚢 Deployment

The site auto-deploys to Vercel on push to main:

• Production: https://smarterwithscience.org
• Preview: Every PR gets a preview URL
• Staging: develop branch deploys to staging

Manual Deploy

# Deploy to production
npm run deploy

# Deploy preview
npm run deploy:preview

🎯 Performance Targets

We maintain strict performance standards:

• First Contentful Paint: <1s
• Time to Interactive: <2s
• Lighthouse Score: >95
• Bundle Size: <50KB JS

📝 Content Guidelines

Writing Style

• Clear: No jargon unless necessary
• Inclusive: Science is for everyone
• Action-oriented: Focus on what people can DO
• Community-first: Highlight collaboration

Image Requirements

• Hero Images: 1920x1080px minimum
• Project Cards: 800x600px
• Format: WebP preferred, PNG/JPG fallback
• Optimization: Run through npm run optimize:images

🤝 Contributing

See CONTRIBUTING.md for detailed guidelines.

Quick version:

1. Fork the repo
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Make changes
4. Run tests (npm run test)
5. Commit (git commit -m 'Add amazing feature')
6. Push (git push origin feature/amazing-feature)
7. Open Pull Request

🐛 Troubleshooting

Common Issues

Port already in use:

# Kill process on port 4321
npx kill-port 4321

Images not loading:

# Regenerate image cache
npm run clean:images
npm run generate:images

Build fails:

# Clear all caches
npm run clean
npm install
npm run build

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Built with Astrowind
• Inspired by the global community science movement
• Powered by curiosity and collaboration

📞 Contact

• Website: smarterwithscience.org
• Email: hello@smarterwithscience.org
• Discord: Join our community
• GitHub: @smarterwithscience

---

Remember: We're not just building a website. We're creating a digital manifestation of humanity's scientific future - where communities lead, technology serves, and wonder drives discovery.

Science for communities, by communities. 💜🔬✨