Jamey Greenwood
6b6c7cc148
- Rewrite README.md with proper project overview, setup, and structure - Create ROADMAP.md capturing future improvements and known gaps - Move reference docs to docs/ directory: - docs/spec.md (theme system specification) - docs/plans/sample-content.md (POD content refresh plan) - docs/plans/page-builder.md (existing) - docs/research/typography.md - docs/research/ux-patterns.md - Delete obsolete planning files: - PLAN.md (work complete) - PHASE_9_PLAN.md (work complete) - PHASE_9_PROGRESS.md (stale tracker) - RECENT_CHANGES.md (stale) - Keep AGENTS.md (Phoenix codegen guidelines) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
133 lines
4.2 KiB
Markdown
133 lines
4.2 KiB
Markdown
# SimpleshopTheme
|
|
|
|
A customisable e-commerce theme system built with Phoenix LiveView. Designed for print-on-demand sellers who want beautiful, professional shops without design expertise.
|
|
|
|
## Features
|
|
|
|
### Theme Editor (`/admin/theme`)
|
|
- **8 curated presets** - Gallery, Studio, Boutique, Bold, Playful, Minimal, Night, Classic
|
|
- **Real-time preview** - See changes instantly across 7 page types
|
|
- **Comprehensive customisation**:
|
|
- Mood (Neutral, Warm, Cool, Dark)
|
|
- Typography (Clean, Editorial, Modern, Classic, Friendly, Minimal)
|
|
- Shape (Sharp, Soft, Round, Pill)
|
|
- Density (Compact, Balanced, Spacious)
|
|
- Accent colours with automatic contrast
|
|
- Layout options (grid columns, header style, width)
|
|
- Feature toggles (announcement bar, sticky header, etc.)
|
|
- **Logo upload** with optional SVG recolouring
|
|
- **Header image** with zoom and position controls
|
|
|
|
### Public Storefront
|
|
- Home page with hero, categories, featured products, testimonials
|
|
- Products listing with grid layout
|
|
- Product detail pages with image gallery
|
|
- Shopping cart page
|
|
- About and Contact pages
|
|
- Themed 404/500 error pages
|
|
|
|
### Technical Highlights
|
|
- CSS custom properties for instant theme switching
|
|
- Three-layer CSS architecture (primitives → attributes → semantic)
|
|
- ETS-based CSS caching for performance
|
|
- SQLite database with BLOB storage for images
|
|
- Shared PageTemplates between preview and live shop
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- Elixir 1.17+
|
|
- Erlang 27+
|
|
- Node.js 20+ (for assets)
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repo-url>
|
|
cd simpleshop_theme
|
|
|
|
# Install dependencies
|
|
mix setup
|
|
|
|
# Start the server
|
|
mix phx.server
|
|
```
|
|
|
|
Visit:
|
|
- **Shop**: http://localhost:4000
|
|
- **Theme Editor**: http://localhost:4000/admin/theme
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
mix test
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
lib/
|
|
├── simpleshop_theme/ # Core business logic
|
|
│ ├── settings.ex # Theme settings context
|
|
│ ├── settings/
|
|
│ │ └── theme_settings.ex # Theme settings schema
|
|
│ ├── media.ex # Image upload handling
|
|
│ └── theme/
|
|
│ ├── css_generator.ex # Generates CSS from settings
|
|
│ ├── css_cache.ex # ETS cache for generated CSS
|
|
│ ├── presets.ex # 8 theme presets
|
|
│ └── preview_data.ex # Mock data for previews
|
|
│
|
|
├── simpleshop_theme_web/ # Web layer
|
|
│ ├── components/
|
|
│ │ ├── layouts/ # App and shop layouts
|
|
│ │ ├── page_templates/ # Shared page templates (*.heex)
|
|
│ │ ├── page_templates.ex # PageTemplates module
|
|
│ │ └── shop_components.ex # Reusable shop UI components
|
|
│ ├── live/
|
|
│ │ ├── theme_live/ # Theme editor LiveView
|
|
│ │ └── shop_live/ # Public shop LiveViews
|
|
│ └── controllers/
|
|
│ └── error_html.ex # Themed error pages
|
|
|
|
assets/css/
|
|
├── app.css # Main stylesheet
|
|
├── theme-layer1-primitives.css # Design tokens
|
|
├── theme-layer2-attributes.css # Theme-specific values
|
|
└── theme-layer3-semantic.css # Component styles
|
|
```
|
|
|
|
## Routes
|
|
|
|
| Path | Description |
|
|
|------|-------------|
|
|
| `/` | Shop home page |
|
|
| `/products` | Products listing |
|
|
| `/products/:id` | Product detail page |
|
|
| `/cart` | Shopping cart |
|
|
| `/about` | About page |
|
|
| `/contact` | Contact page |
|
|
| `/admin/theme` | Theme editor (requires auth) |
|
|
| `/dev/errors/404` | Preview 404 page (dev only) |
|
|
| `/dev/errors/500` | Preview 500 page (dev only) |
|
|
|
|
## Documentation
|
|
|
|
- [ROADMAP.md](ROADMAP.md) - Future features and improvements
|
|
- [docs/spec.md](docs/spec.md) - Theme system specification
|
|
- [docs/plans/](docs/plans/) - Feature plans
|
|
- [docs/research/](docs/research/) - Design research and guidelines
|
|
|
|
## Design Philosophy
|
|
|
|
1. **"One theme, infinite variations"** - Rather than multiple themes, one solid foundation with curated customisation
|
|
2. **Constrained creativity** - Limit choices to prevent poor design outcomes
|
|
3. **No professional photography required** - Works with product mockups
|
|
4. **Mobile-first** - All features work on touch devices
|
|
5. **Ethical design** - No dark patterns or fake urgency
|
|
|
|
## License
|
|
|
|
MIT
|