1463 lines
60 KiB
Markdown
1463 lines
60 KiB
Markdown
# SmartTools Web UI Design
|
||
|
||
## Purpose
|
||
Deliver a professional web front-end that explains SmartTools, helps users discover tools, and supports a collaborative ecosystem. The site should drive sustainable revenue without undermining trust or usability.
|
||
|
||
## Mission Alignment
|
||
This web UI serves the broader SmartTools mission: to provide a **universally accessible development ecosystem** that empowers regular people to collaborate and build upon each other's progress rather than compete. Revenue generated supports:
|
||
- Maintaining and expanding the project
|
||
- Future hosting of AI models for users with less access to paid services
|
||
- Building a sustainable, community-first platform
|
||
|
||
The UI design must reflect these values through its structure, content, and monetization approach.
|
||
|
||
## Guiding Principles
|
||
- **Utility first**: Documentation, tutorials, and examples are the primary draw.
|
||
- **Trust and clarity**: Ads and monetization are transparent, minimal, and never block core flows.
|
||
- **Collaboration over competition**: Highlight contributors, shared projects, and community learning.
|
||
- **Performance and accessibility**: Fast, readable, WCAG 2.1 AA target.
|
||
- **Unix philosophy**: Composable, provider-agnostic, YAML-based tools—the UI should communicate this clearly.
|
||
|
||
## Information Architecture
|
||
Public, ad-supported (Tier 1):
|
||
- `/` landing
|
||
- `/docs/*` documentation
|
||
- `/tutorials/*`
|
||
- `/examples`
|
||
- `/blog`
|
||
- `/about`
|
||
- `/donate`
|
||
|
||
Registry (Tier 2, ad-free):
|
||
- `/tools`
|
||
- `/tools/{owner}/{name}`
|
||
- `/categories`
|
||
- `/categories/{name}`
|
||
- `/search`
|
||
|
||
Community (Tier 3, light ads):
|
||
- `/forum`
|
||
- `/contributors`
|
||
- `/announcements`
|
||
|
||
Publisher dashboard (auth-only):
|
||
- `/register`, `/login`
|
||
- `/dashboard/tools`
|
||
- `/dashboard/tokens`
|
||
- `/dashboard/settings`
|
||
|
||
API:
|
||
- `/api/v1/*` (shared with CLI)
|
||
|
||
## Visual Design System
|
||
|
||
### Color Palette
|
||
|
||
| Role | Color | Hex | Usage |
|
||
|------|-------|-----|-------|
|
||
| Primary | Indigo | `#6366F1` | CTAs, active states, brand identity |
|
||
| Secondary | Cyan | `#06B6D4` | Secondary actions, accents, links |
|
||
| Background | Off-white | `#F9FAFB` | Page background |
|
||
| Surface | White | `#FFFFFF` | Cards, content areas |
|
||
| Text Primary | Dark gray | `#1F2937` | Headlines, body text |
|
||
| Text Secondary | Medium gray | `#6B7280` | Descriptions, metadata |
|
||
| Text Muted | Light gray | `#9CA3AF` | Timestamps, hints |
|
||
| Border | Light gray | `#E5E7EB` | Card borders, dividers |
|
||
| Success | Green | `#10B981` | Success states, confirmations |
|
||
| Warning | Amber | `#F59E0B` | Warnings, deprecation notices |
|
||
| Error | Red | `#EF4444` | Error states, critical alerts |
|
||
| Header | Dark slate | `#2C3E50` | Header background |
|
||
| Ad Container | Light blue | `#DBEAFE` | Ad zone background (distinct from content) |
|
||
| Sponsored | Light amber | `#FEF3C7` | Sponsored content background |
|
||
|
||
**Contrast Requirements:**
|
||
- Body text: minimum 4.5:1 ratio (WCAG AA)
|
||
- Large text (18px+): minimum 3:1 ratio
|
||
- UI components: minimum 3:1 ratio against adjacent colors
|
||
|
||
### Typography
|
||
|
||
| Element | Font | Size | Weight | Line Height |
|
||
|---------|------|------|--------|-------------|
|
||
| H1 | Inter/system-ui | 36px (2.25rem) | 700 | 1.2 |
|
||
| H2 | Inter/system-ui | 24px (1.5rem) | 700 | 1.3 |
|
||
| H3 | Inter/system-ui | 20px (1.25rem) | 600 | 1.4 |
|
||
| H4 | Inter/system-ui | 18px (1.125rem) | 600 | 1.4 |
|
||
| Body | Inter/system-ui | 16px (1rem) | 400 | 1.6 |
|
||
| Small | Inter/system-ui | 14px (0.875rem) | 400 | 1.5 |
|
||
| Code | JetBrains Mono/monospace | 14px | 400 | 1.5 |
|
||
| Code block | JetBrains Mono/monospace | 13px | 400 | 1.6 |
|
||
|
||
**Font Stack:**
|
||
```css
|
||
--font-sans: 'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif;
|
||
--font-mono: 'JetBrains Mono', ui-monospace, 'Cascadia Code', monospace;
|
||
```
|
||
|
||
### Spacing System
|
||
|
||
Use an 8px base grid for consistent spacing:
|
||
|
||
| Token | Value | Usage |
|
||
|-------|-------|-------|
|
||
| `--space-1` | 4px | Tight spacing, icon margins |
|
||
| `--space-2` | 8px | Element gaps |
|
||
| `--space-3` | 12px | Small component padding |
|
||
| `--space-4` | 16px | Card padding, section gaps |
|
||
| `--space-6` | 24px | Section padding |
|
||
| `--space-8` | 32px | Large gaps |
|
||
| `--space-12` | 48px | Section margins |
|
||
| `--space-16` | 64px | Major section separators |
|
||
|
||
### Border Radius
|
||
|
||
| Token | Value | Usage |
|
||
|-------|-------|-------|
|
||
| `--radius-sm` | 4px | Buttons, badges |
|
||
| `--radius-md` | 8px | Cards, inputs |
|
||
| `--radius-lg` | 12px | Modals, large cards |
|
||
| `--radius-full` | 9999px | Avatars, pills |
|
||
|
||
### Shadow System
|
||
|
||
```css
|
||
--shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
|
||
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
|
||
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
|
||
--shadow-hover: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
|
||
```
|
||
|
||
## Page Requirements
|
||
|
||
### Landing Page (`/`)
|
||
|
||
**Purpose:** Convert visitors to users by clearly communicating SmartTools' value proposition and providing immediate paths to explore.
|
||
|
||
**Reference mockup:** `discussions/diagrams/smarttools-registry_rob_6.svg`
|
||
|
||
#### Section 1: Hero (Above the Fold)
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ [SmartTools] Docs Tutorials Registry Community About 🔍 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Build Custom AI Commands in YAML │
|
||
│ ───────────────────────────────────────────────────────── │
|
||
│ Create Unix-style pipeable tools that work with any AI │
|
||
│ provider. Provider-agnostic and composable. │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ $ pip install smarttools && smarttools init │ [📋]│
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ [Get Started] [View Tutorials] │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Content:**
|
||
- **Headline:** "Build Custom AI Commands in YAML" (benefit-focused, differentiating)
|
||
- **Subheadline:** "Create Unix-style pipeable tools that work with any AI provider. Provider-agnostic and composable for ultimate flexibility."
|
||
- **Install snippet:** `pip install smarttools && smarttools init` with copy button
|
||
- **Primary CTA:** "Get Started" → links to `/docs/getting-started` (indigo background)
|
||
- **Secondary CTA:** "View Tutorials" → links to `/tutorials` (outlined, cyan border)
|
||
|
||
**Design Notes:**
|
||
- Hero background: white card (#FFFFFF) with subtle shadow on off-white page
|
||
- Maximum content width: 1100px centered
|
||
- Install snippet: monospace font, light gray background (#E0E0E0), copy icon on right
|
||
|
||
#### Section 2: Three Pillars (Why SmartTools?)
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Why SmartTools? │
|
||
├──────────────────┬──────────────────┬────────────────────────────┤
|
||
│ [✓] Easy │ [⚡] Powerful │ [👥] Community │
|
||
│ │ │ │
|
||
│ Simple YAML │ Any AI │ Share, discover, │
|
||
│ configuration │ provider, │ contribute to a │
|
||
│ for quick │ compose │ growing ecosystem. │
|
||
│ setup. │ complex │ │
|
||
│ │ workflows. │ │
|
||
└──────────────────┴──────────────────┴────────────────────────────┘
|
||
```
|
||
|
||
**Content:**
|
||
- **Pillar 1 - Easy to Use:** Icon in indigo circle, "Simple YAML configuration for quick setup."
|
||
- **Pillar 2 - Powerful:** Icon in cyan circle, "Leverage any AI provider, compose complex workflows."
|
||
- **Pillar 3 - Community:** Icon in indigo circle, "Share, discover, and contribute to a growing ecosystem."
|
||
|
||
**Design Notes:**
|
||
- Each pillar: white card with 1px border, subtle shadow on hover
|
||
- Icon circles: 40px diameter with pillar icon centered
|
||
- Equal width columns (3 across on desktop)
|
||
|
||
#### Section 3: Featured Tools & Projects
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Featured Tools & Projects │
|
||
├──────────────────┬──────────────────┬────────────────────────────┤
|
||
│ [Category] │ [Category] │ [Category] │
|
||
│ ● Tool Title │ ● Tool Title │ ● Tool Title │
|
||
│ Description... │ Description... │ Description... │
|
||
│ Author: name │ Author: name │ Author: name │
|
||
│ Downloads: 1.2K │ Downloads: 800 │ Downloads: 2.5K │
|
||
│ ┌────────────┐ │ ┌────────────┐ │ ┌────────────┐ │
|
||
│ │run command │ │ │run command │ │ │run command │ │
|
||
│ └────────────┘ │ └────────────┘ │ └────────────┘ │
|
||
├──────────────────┼──────────────────┼────────────────────────────┤
|
||
│ [Row 2...] │ [Row 2...] │ [Row 2...] │
|
||
└──────────────────┴──────────────────┴────────────────────────────┘
|
||
```
|
||
|
||
**Content (per card):**
|
||
- Category badge (top-right, cyan pill)
|
||
- Tool icon/avatar (indigo circle)
|
||
- Tool name (bold, 18px)
|
||
- Short description (14px, secondary text)
|
||
- Author attribution
|
||
- Download count with icon
|
||
- One-line install command in code box
|
||
|
||
**Data Source:** `GET /api/v1/tools?sort=downloads&limit=6`
|
||
|
||
**Design Notes:**
|
||
- 3 columns on desktop, 2 on tablet, 1 on mobile
|
||
- Cards have subtle shadow, lift on hover
|
||
- "View All Tools" link below grid → `/tools`
|
||
|
||
#### Section 4: Getting Started
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Getting Started │
|
||
├──────────────────┬──────────────────┬────────────────────────────┤
|
||
│ Tutorial 1: │ Tutorial 2: │ Tutorial 3: │
|
||
│ Basic Setup │ Your First Tool │ Advanced Workflows │
|
||
│ Learn how to... │ Create a │ Combine multiple │
|
||
│ │ simple AI... │ tools for... │
|
||
│ [Read More] │ [Read More] │ [Read More] │
|
||
└──────────────────┴──────────────────┴────────────────────────────┘
|
||
```
|
||
|
||
**Content:**
|
||
- 3 tutorial cards highlighting core learning paths
|
||
- Each card: title (bold), description (2 lines max), CTA button
|
||
|
||
**Design Notes:**
|
||
- Matches tool card styling for visual consistency
|
||
- "Read More" buttons in primary indigo
|
||
|
||
#### Section 5: Featured Contributor
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Featured Contributor │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ [Avatar] Name Here │
|
||
│ Creator of "Tool Name" and active community member. │
|
||
│ [View Profile] │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Content:**
|
||
- Monthly rotating spotlight
|
||
- Avatar (60px circle), name, brief bio, profile link
|
||
|
||
**Data Source:** Manual curation or `GET /api/v1/contributors/featured`
|
||
|
||
#### Section 6: Footer Ad Zone (Optional)
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ [Advertisement: Support SmartTools Development] │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Design Notes:**
|
||
- Light blue background (#DBEAFE) to distinguish from content
|
||
- Clearly labeled as advertisement
|
||
- Optional based on ad fill rate
|
||
|
||
#### Section 7: Footer
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ SmartTools │
|
||
│ ───────────────────────────────────────────────────────────── │
|
||
│ Docs | Registry | Community | About | Donate │
|
||
│ Privacy | Terms | GitHub | Twitter │
|
||
│ │
|
||
│ © 2025 SmartTools. Open source under MIT License. │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Docs/Tutorials Pages (`/docs/*`, `/tutorials/*`)
|
||
|
||
**Layout:**
|
||
```
|
||
┌───────────────────────────────────────────────────────────────────────┐
|
||
│ [Header Navigation] │
|
||
├──────────────┬────────────────────────────────────────────┬───────────┤
|
||
│ TOC │ Content Area (70%) │ Sidebar │
|
||
│ (Desktop) │ │ (Ads) │
|
||
│ │ # Page Title │ │
|
||
│ - Section 1 │ │ [Ad] │
|
||
│ - Section 2 │ Content with code blocks... │ │
|
||
│ - Section 3 │ │ │
|
||
│ │ ```python │ │
|
||
│ │ # Code with syntax highlighting │ │
|
||
│ │ ``` [Copy] │ │
|
||
│ │ │ │
|
||
│ │ [Embedded Video] │ │
|
||
│ │ │ │
|
||
└──────────────┴────────────────────────────────────────────┴───────────┘
|
||
```
|
||
|
||
**Content Requirements:**
|
||
- Persistent left TOC on desktop (scroll-spy highlighting current section)
|
||
- Code blocks with syntax highlighting and copy button
|
||
- Video embeds (YouTube) with play button overlay, lazy-loaded
|
||
- Callout boxes for tips, warnings, info (color-coded)
|
||
- Related articles at bottom
|
||
|
||
**Design Notes:**
|
||
- TOC: fixed on scroll, 200px width
|
||
- Content area: max-width 700px, generous line-height (1.6-1.8)
|
||
- Sidebar ads: 300px width, only on desktop
|
||
- Mobile: TOC collapses to hamburger, sidebar hidden
|
||
|
||
### Tool Detail Page (`/tools/{owner}/{name}`)
|
||
|
||
**Layout:**
|
||
```
|
||
┌───────────────────────────────────────────────────────────────────────┐
|
||
│ [Header Navigation] │
|
||
├─────────────────────────────────────────────────────┬─────────────────┤
|
||
│ README Content (70%) │ Sidebar (30%) │
|
||
│ │ │
|
||
│ # tool-name │ ┌───────────┐ │
|
||
│ │ │Install │ │
|
||
│ Rendered markdown from README.md... │ │ │ │
|
||
│ │ │$ run cmd │ │
|
||
│ - Usage examples │ └───────────┘ │
|
||
│ - Configuration │ │
|
||
│ - Step definitions │ Versions: │
|
||
│ │ v1.2.0 ● │
|
||
│ │ v1.1.0 │
|
||
│ │ v1.0.0 │
|
||
│ │ │
|
||
│ │ Downloads: │
|
||
│ │ 1,234 │
|
||
│ │ │
|
||
│ │ Category: │
|
||
│ │ [text-proc] │
|
||
│ │ │
|
||
│ │ Tags: │
|
||
│ │ [ai] [cli] │
|
||
│ │ │
|
||
│ │ [Report] │
|
||
└─────────────────────────────────────────────────────┴─────────────────┘
|
||
```
|
||
|
||
**Sidebar Elements:**
|
||
- Install command with copy button (prominent)
|
||
- Version selector/list (current version highlighted)
|
||
- Download statistics
|
||
- Category badge (linked)
|
||
- Tags (linked to search)
|
||
- Report abuse button
|
||
- Publisher info (avatar, name, link to profile)
|
||
|
||
**NO ADS on tool detail pages** (Tier 2 - registry is ad-free)
|
||
|
||
### Registry Browse Page (`/tools`)
|
||
|
||
**Layout:**
|
||
```
|
||
┌───────────────────────────────────────────────────────────────────────┐
|
||
│ [Header Navigation] │
|
||
├───────────────────────────────────────────────────────────────────────┤
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 🔍 Search tools... [Category ▼] [Sort ▼] │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
├───────────────────────────────────────────────────────────────────────┤
|
||
│ Showing 142 tools │
|
||
├──────────────────┬──────────────────┬──────────────────┬──────────────┤
|
||
│ [Tool Card] │ [Tool Card] │ [Tool Card] │ [Tool Card] │
|
||
│ │ │ │ │
|
||
├──────────────────┼──────────────────┼──────────────────┼──────────────┤
|
||
│ [Tool Card] │ [Tool Card] │ [Tool Card] │ [Tool Card] │
|
||
│ │ │ │ │
|
||
├───────────────────────────────────────────────────────────────────────┤
|
||
│ [← Previous] Page 1 of 8 [Next →] │
|
||
└───────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Search/Filter Features:**
|
||
- Full-text search with debounce (300ms)
|
||
- Category dropdown filter
|
||
- Sort options: Popular (downloads), Recent, Name
|
||
- Results count display
|
||
- Pagination (20 per page)
|
||
|
||
**Tool Card (compact):**
|
||
- Tool name + owner
|
||
- Short description (2 lines max, truncated)
|
||
- Download count
|
||
- Last updated date
|
||
- Category tag
|
||
|
||
**NO ADS on browse pages** (Tier 2)
|
||
|
||
### Publisher Dashboard (`/dashboard`)
|
||
|
||
**Layout:**
|
||
```
|
||
┌───────────────────────────────────────────────────────────────────────┐
|
||
│ [Header with user menu] │
|
||
├─────────────────┬─────────────────────────────────────────────────────┤
|
||
│ Sidebar │ Content Area │
|
||
│ │ │
|
||
│ My Tools │ ┌─ Tab: My Tools ──────────────────────────────┐ │
|
||
│ API Tokens │ │ │ │
|
||
│ Settings │ │ Published Tools (3) [+ New Tool] │ │
|
||
│ │ │ ┌─────────────────────────────────────────┐ │ │
|
||
│ │ │ │ summarize v1.2.0 | 142 downloads │ │ │
|
||
│ │ │ │ [Edit] [View] [Yank] │ │ │
|
||
│ │ │ └─────────────────────────────────────────┘ │ │
|
||
│ │ │ │ │
|
||
│ │ │ Pending PRs (1) │ │
|
||
│ │ │ ┌─────────────────────────────────────────┐ │ │
|
||
│ │ │ │ new-tool v1.0.0 | Awaiting review │ │ │
|
||
│ │ │ │ [View PR] │ │ │
|
||
│ │ │ └─────────────────────────────────────────┘ │ │
|
||
│ │ └──────────────────────────────────────────────┘ │
|
||
└─────────────────┴─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Tabs:**
|
||
1. **My Tools:** List of published tools with stats, edit/view/yank actions
|
||
2. **API Tokens:** Token management table (name, created, last used, revoke)
|
||
3. **Settings:** Profile editing (display name, bio, website), password change
|
||
|
||
**Design Notes:**
|
||
- Clean, utilitarian design
|
||
- Clear action buttons
|
||
- Status indicators for pending PRs
|
||
- Token creation shows token only once with copy functionality
|
||
|
||
### Donate Page (`/donate`)
|
||
|
||
**Content:**
|
||
- Mission statement (emotional, connecting to values)
|
||
- Clear explanation of fund usage (hosting, development, future AI hosting)
|
||
- Multiple donation options (GitHub Sponsors, PayPal, Ko-fi)
|
||
- Optional donor recognition section
|
||
- Transparency about current costs/goals
|
||
|
||
**Design Notes:**
|
||
- Clean, trustworthy design
|
||
- Clear CTAs for each donation method
|
||
- No ads on this page
|
||
|
||
## Component Library
|
||
|
||
### Buttons
|
||
|
||
**Primary Button:**
|
||
```html
|
||
<button class="btn-primary">Get Started</button>
|
||
```
|
||
- Background: Primary indigo (#6366F1)
|
||
- Text: White, 16px, font-weight 600
|
||
- Padding: 12px 24px
|
||
- Border-radius: 4px
|
||
- Hover: Darken 10%, subtle shadow
|
||
- Focus: 2px outline offset
|
||
|
||
**Secondary Button:**
|
||
```html
|
||
<button class="btn-secondary">View Tutorials</button>
|
||
```
|
||
- Background: Transparent
|
||
- Border: 2px solid cyan (#06B6D4)
|
||
- Text: Cyan, 16px, font-weight 600
|
||
- Hover: Light cyan background (#ECFEFF)
|
||
|
||
**Ghost Button:**
|
||
```html
|
||
<button class="btn-ghost">Read More</button>
|
||
```
|
||
- Background: Transparent
|
||
- Text: Primary indigo
|
||
- Hover: Light indigo background
|
||
|
||
**Danger Button:**
|
||
```html
|
||
<button class="btn-danger">Revoke Token</button>
|
||
```
|
||
- Background: Error red (#EF4444)
|
||
- Text: White
|
||
- Used for destructive actions
|
||
|
||
### Cards
|
||
|
||
**Tool Card:**
|
||
```
|
||
┌───────────────────────────────────────┐
|
||
│ [Category] │
|
||
│ [●] Tool Name │
|
||
│ Short description of the tool that │
|
||
│ may span two lines maximum... │
|
||
│ │
|
||
│ Author: owner-name │
|
||
│ ⬇ 1,234 downloads │
|
||
│ │
|
||
│ ┌─────────────────────────────────┐ │
|
||
│ │ smarttools run owner/tool │ │
|
||
│ └─────────────────────────────────┘ │
|
||
└───────────────────────────────────────┘
|
||
```
|
||
- Background: White (#FFFFFF)
|
||
- Border: 1px solid border color (#E5E7EB)
|
||
- Border-radius: 8px
|
||
- Shadow: shadow-sm, shadow-md on hover
|
||
- Padding: 16px
|
||
- Category badge: absolute top-right, cyan background, white text, 12px
|
||
|
||
**Tutorial Card:**
|
||
```
|
||
┌───────────────────────────────────────┐
|
||
│ [Optional Thumbnail Image] │
|
||
│ │
|
||
│ Tutorial Title Here │
|
||
│ Brief description of what the │
|
||
│ tutorial covers... │
|
||
│ │
|
||
│ [Read More →] │
|
||
└───────────────────────────────────────┘
|
||
```
|
||
- Same base styling as tool card
|
||
- Optional thumbnail: aspect-ratio 16:9, lazy-loaded
|
||
|
||
**Contributor Card:**
|
||
```
|
||
┌───────────────────────────────────────┐
|
||
│ [Avatar] Contributor Name │
|
||
│ @github-handle │
|
||
│ Creator of "Tool Name" │
|
||
│ [View Profile] │
|
||
└───────────────────────────────────────┘
|
||
```
|
||
- Avatar: 48px circle
|
||
- Horizontal layout for spotlight, vertical for grid
|
||
|
||
### Navigation
|
||
|
||
**Header Navigation:**
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ [Logo] [Docs] [Tutorials] [Registry] [Community] [About] 🔍 │
|
||
│ [Donate] │
|
||
└─────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
- Background: Dark slate (#2C3E50)
|
||
- Logo: White text, 24px, bold
|
||
- Nav links: White text, 16px
|
||
- Active/hover: Underline or slight background
|
||
- Mobile: Hamburger menu with slide-out drawer
|
||
|
||
**Breadcrumbs:**
|
||
```
|
||
Registry > owner > tool-name > v1.2.0
|
||
```
|
||
- Separator: `>` or `/`
|
||
- Current page: bold, not linked
|
||
- Previous pages: linked, secondary color
|
||
|
||
### Form Elements
|
||
|
||
**Text Input:**
|
||
```html
|
||
<input type="text" class="input" placeholder="Search tools...">
|
||
```
|
||
- Border: 1px solid border color
|
||
- Border-radius: 8px
|
||
- Padding: 12px 16px
|
||
- Focus: Primary indigo border, subtle shadow
|
||
- Height: 44px (touch target compliance)
|
||
|
||
**Search Input with Icon:**
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ 🔍 Search tools... │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
- Icon: Left-aligned, muted color
|
||
- Placeholder: Secondary text color
|
||
|
||
**Select/Dropdown:**
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ Category ▼ │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
- Same styling as text input
|
||
- Chevron icon on right
|
||
|
||
### Badges and Tags
|
||
|
||
**Category Badge:**
|
||
```html
|
||
<span class="badge badge-category">text-processing</span>
|
||
```
|
||
- Background: Cyan (#06B6D4)
|
||
- Text: White, 12px
|
||
- Padding: 4px 8px
|
||
- Border-radius: 4px
|
||
|
||
**Tag:**
|
||
```html
|
||
<span class="tag">ai</span>
|
||
```
|
||
- Background: Light gray (#F3F4F6)
|
||
- Text: Secondary gray, 12px
|
||
- Border: 1px solid border color
|
||
- Border-radius: 9999px (pill)
|
||
- Clickable (links to search)
|
||
|
||
**Status Badge:**
|
||
```html
|
||
<span class="badge badge-success">Published</span>
|
||
<span class="badge badge-warning">Pending</span>
|
||
<span class="badge badge-error">Yanked</span>
|
||
```
|
||
- Success: Green background
|
||
- Warning: Amber background
|
||
- Error: Red background
|
||
|
||
### Code Blocks
|
||
|
||
**Inline Code:**
|
||
```html
|
||
<code>smarttools run foo</code>
|
||
```
|
||
- Background: Light gray (#F3F4F6)
|
||
- Font: Monospace
|
||
- Padding: 2px 6px
|
||
- Border-radius: 4px
|
||
|
||
**Code Block with Copy:**
|
||
```
|
||
┌───────────────────────────────────────────────────────┐
|
||
│ ```python [📋] │
|
||
│ def hello(): │
|
||
│ print("Hello, World!") │
|
||
│ ``` │
|
||
└───────────────────────────────────────────────────────┘
|
||
```
|
||
- Background: Dark (#1F2937) or light (#F9FAFB)
|
||
- Syntax highlighting (Prism.js or Highlight.js)
|
||
- Copy button: top-right, appears on hover
|
||
- Line numbers: optional, enabled for tutorials
|
||
|
||
### Callout Boxes
|
||
|
||
**Info Callout:**
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ ℹ️ Note │
|
||
│ This is helpful information for the user. │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
- Background: Light blue (#DBEAFE)
|
||
- Border-left: 4px solid blue (#3B82F6)
|
||
|
||
**Warning Callout:**
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ ⚠️ Warning │
|
||
│ Be careful with this configuration. │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
- Background: Light amber (#FEF3C7)
|
||
- Border-left: 4px solid amber (#F59E0B)
|
||
|
||
**Error Callout:**
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ ❌ Important │
|
||
│ This action cannot be undone. │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
- Background: Light red (#FEE2E2)
|
||
- Border-left: 4px solid red (#EF4444)
|
||
|
||
**Tip Callout:**
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 💡 Tip │
|
||
│ You can also use this shortcut... │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
- Background: Light green (#D1FAE5)
|
||
- Border-left: 4px solid green (#10B981)
|
||
|
||
### Loading States
|
||
|
||
**Skeleton Loader:**
|
||
```
|
||
┌───────────────────────────────────────┐
|
||
│ ████████████████ │
|
||
│ ████████████████████████████████ │
|
||
│ ████████████ │
|
||
└───────────────────────────────────────┘
|
||
```
|
||
- Animated shimmer effect
|
||
- Matches component dimensions
|
||
- Used for cards, text blocks
|
||
|
||
**Spinner:**
|
||
- Circular spinner for buttons, inline loading
|
||
- Primary indigo color
|
||
- Size: 16px (small), 24px (medium), 32px (large)
|
||
|
||
**Progress Bar:**
|
||
- Used for multi-step operations
|
||
- Shows percentage or step count
|
||
|
||
## Responsive Design
|
||
|
||
### Breakpoints
|
||
|
||
| Breakpoint | Width | Name | Grid Columns |
|
||
|------------|-------|------|--------------|
|
||
| xs | < 480px | Extra small phones | 1 |
|
||
| sm | 480-639px | Phones | 1 |
|
||
| md | 640-767px | Large phones / small tablets | 2 |
|
||
| lg | 768-1023px | Tablets | 2-3 |
|
||
| xl | 1024-1279px | Small desktops | 3-4 |
|
||
| 2xl | ≥ 1280px | Large desktops | 4 |
|
||
|
||
### Layout Adaptations
|
||
|
||
**Mobile (< 640px):**
|
||
- Single-column layout
|
||
- Navigation: hamburger menu with slide-out drawer
|
||
- Hero: stacked content, centered
|
||
- Tool cards: full-width, stacked
|
||
- TOC: collapsible accordion at top of page
|
||
- Sidebar ads: hidden
|
||
- Footer ads: optional, minimal
|
||
|
||
**Tablet (640-1023px):**
|
||
- Two-column grid for cards
|
||
- Navigation: horizontal but condensed
|
||
- TOC: collapsible sidebar
|
||
- Sidebar ads: may show below content
|
||
|
||
**Desktop (≥ 1024px):**
|
||
- Full multi-column layout
|
||
- Navigation: full horizontal with all links visible
|
||
- TOC: fixed left sidebar
|
||
- Sidebar ads: visible in right column
|
||
- Maximum content width: 1280px with centered container
|
||
|
||
### Touch Targets
|
||
|
||
All interactive elements must meet minimum touch target size:
|
||
- Minimum size: 44×44px (WCAG 2.1 AA)
|
||
- Spacing between targets: minimum 8px
|
||
- Applies to: buttons, links, form inputs, navigation items
|
||
|
||
### Mobile-Specific Considerations
|
||
|
||
- No horizontal scrolling
|
||
- Images: responsive with max-width: 100%
|
||
- Tables: horizontal scroll wrapper on small screens
|
||
- Code blocks: horizontal scroll with visible scrollbar
|
||
- Modals: full-screen on mobile, centered on desktop
|
||
- Keyboard: virtual keyboard should not obscure inputs
|
||
|
||
## Performance Budgets
|
||
|
||
### Core Web Vitals Targets
|
||
|
||
| Metric | Target | Maximum |
|
||
|--------|--------|---------|
|
||
| Largest Contentful Paint (LCP) | < 1.5s | < 2.5s |
|
||
| First Input Delay (FID) | < 50ms | < 100ms |
|
||
| Cumulative Layout Shift (CLS) | < 0.05 | < 0.1 |
|
||
| First Contentful Paint (FCP) | < 1.0s | < 1.8s |
|
||
| Time to Interactive (TTI) | < 2.5s | < 3.5s |
|
||
|
||
### Resource Budgets
|
||
|
||
| Resource | Budget | Notes |
|
||
|----------|--------|-------|
|
||
| Total page weight | < 500KB | Excluding ads |
|
||
| JavaScript (compressed) | < 100KB | Main bundle |
|
||
| CSS (compressed) | < 50KB | Main stylesheet |
|
||
| Images (above fold) | < 200KB | Hero, featured tools |
|
||
| Fonts | < 100KB | Subset, WOFF2 format |
|
||
| Third-party scripts | < 150KB | Analytics, ads (lazy) |
|
||
|
||
### Loading Strategy
|
||
|
||
**Critical Path (synchronous):**
|
||
1. HTML document
|
||
2. Critical CSS (inlined in `<head>`)
|
||
3. Above-the-fold content
|
||
|
||
**Deferred Loading:**
|
||
1. Non-critical CSS (preload, async)
|
||
2. JavaScript (defer)
|
||
3. Below-fold images (lazy-load with `loading="lazy"`)
|
||
4. Third-party scripts (ads, analytics)
|
||
5. Video embeds (lazy, placeholder until visible)
|
||
|
||
### Caching Strategy
|
||
|
||
| Resource | Cache-Control | Notes |
|
||
|----------|---------------|-------|
|
||
| Static assets (CSS, JS) | `max-age=31536000, immutable` | Hashed filenames |
|
||
| Images | `max-age=86400` | 1 day |
|
||
| HTML pages | `max-age=300, stale-while-revalidate=60` | 5 min, background refresh |
|
||
| API responses | `max-age=60` | 1 min for tool lists |
|
||
| Tool downloads | `max-age=3600, immutable` | Immutable versions |
|
||
|
||
### Performance Monitoring
|
||
|
||
- Monitor Core Web Vitals in production
|
||
- Set up alerts for degradation (>10% threshold)
|
||
- Track page load times by route
|
||
- Monitor JavaScript error rates
|
||
|
||
## Error States and Fallbacks
|
||
|
||
### Network Errors
|
||
|
||
**API Unavailable:**
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ ⚠️ Registry Temporarily Unavailable │
|
||
│ │
|
||
│ We're having trouble connecting to the registry. │
|
||
│ Please try again in a few moments. │
|
||
│ │
|
||
│ [Retry] │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Slow Connection:**
|
||
- Show skeleton loaders for content
|
||
- Progressive loading with visible feedback
|
||
- Timeout after 10 seconds with retry option
|
||
|
||
### Tool Not Found (404):
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Tool Not Found │
|
||
│ │
|
||
│ The tool "owner/tool-name" doesn't exist or may │
|
||
│ have been removed. │
|
||
│ │
|
||
│ [Browse Tools] [Search Registry] │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Search No Results:
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ No tools found for "query" │
|
||
│ │
|
||
│ Suggestions: │
|
||
│ • Try different keywords │
|
||
│ • Check spelling │
|
||
│ • Browse by category │
|
||
│ │
|
||
│ [Browse All Tools] │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Offline Mode
|
||
|
||
If service worker is implemented:
|
||
- Show cached pages when offline
|
||
- Indicate offline status in header
|
||
- Queue actions (report, install) for when online
|
||
|
||
### Form Errors
|
||
|
||
**Inline Validation:**
|
||
- Show error message below field
|
||
- Red border on invalid fields
|
||
- Error icon in field
|
||
|
||
**Form Submission Error:**
|
||
- Toast notification for transient errors
|
||
- Inline error summary for validation failures
|
||
- Preserve form state on error
|
||
|
||
## Ad and Revenue Strategy
|
||
- **Ad placement**: One sidebar unit on long-form docs/tut pages, optional footer banner on landing, none on registry pages.
|
||
- **No ads** in install flows, login/registration, or tool browsing details.
|
||
- **Sponsored content**: Clearly labeled and separated from organic rankings.
|
||
- **YouTube**: Embed tutorials with transcripts; also drive to channel.
|
||
|
||
## Monetization Extensions (Optional)
|
||
- **Donations**: Single page with clear use-of-funds.
|
||
- **Featured projects**: Curated or sponsored slots with explicit labeling.
|
||
- **Premium publisher tier**: More tools, enhanced analytics, priority review.
|
||
- **Training/consulting**: Workshops or enterprise onboarding.
|
||
|
||
## Data and Governance
|
||
Proposed minimal tables (web-only):
|
||
- `promotions` (featured tools/projects, start/end, placement, audit).
|
||
- `featured_projects` (title, description, owner, url, status).
|
||
- `content_pages` (docs/tutorials metadata for listing).
|
||
- `announcements` (title, body, published_at).
|
||
|
||
Roles and permissions:
|
||
- `admin`: can publish announcements, manage promotions, moderate reports.
|
||
- `editor`: can create/update docs, tutorials, featured projects.
|
||
- `publisher`: can manage their own tools and profile only.
|
||
- `contributor`: can partisipate in discussions in the forums.
|
||
|
||
Audit fields (required on content tables):
|
||
- `created_by`, `updated_by`, `created_at`, `updated_at`.
|
||
|
||
Ranking rules:
|
||
- Organic search uses relevance and downloads.
|
||
- Sponsored placements appear in dedicated sections and do not alter organic order.
|
||
|
||
Promotions placement rules:
|
||
- Slots are deterministic (e.g., positions 1 and 5 in lists).
|
||
- Promotions are clearly labeled and never mixed into organic ranking.
|
||
- `promotions` includes `placement`, `priority`, `start_at`, `end_at`, `status`.
|
||
|
||
## Privacy and Consent
|
||
- Consent banner for analytics/ads.
|
||
- Minimal tracking, anonymized IPs.
|
||
- Clear privacy policy and retention policy.
|
||
|
||
Consent storage:
|
||
- Store a `consents` record keyed by `client_id` (anonymous) or user id (logged-in).
|
||
- Respect opt-outs by disabling analytics/ads on server-rendered pages.
|
||
|
||
## UX and Accessibility
|
||
- Keyboard navigation for all interactive elements.
|
||
- High contrast and readable typography.
|
||
- Mobile-first layout; ads hidden on mobile except optional footer.
|
||
- Avoid popups and auto-play media.
|
||
|
||
Responsive breakpoints (baseline):
|
||
- Mobile: <640px
|
||
- Tablet: 640–1024px
|
||
- Desktop: >1024px
|
||
|
||
## Tech Stack (Phase 7 Target)
|
||
- **Flask + Jinja + Tailwind** for SEO-friendly server-rendered pages.
|
||
- Optional **htmx** or **Alpine.js** for small interactivity.
|
||
- Shared registry API for data.
|
||
|
||
## Auth and Session Model
|
||
- Server-side sessions (DB-backed) for dashboard views.
|
||
- Cookies: `HttpOnly`, `SameSite=Lax`, `Secure` in production.
|
||
- CSRF protection on all POST/PUT/DELETE web forms.
|
||
- Session TTL: 7 days with rotation on login.
|
||
- Logout invalidates session server-side.
|
||
|
||
## API Surfaces for Web UI
|
||
Read-only UI calls should use the existing API:
|
||
- `/api/v1/tools`, `/api/v1/tools/search`, `/api/v1/categories`, `/api/v1/stats/popular`.
|
||
|
||
Publisher dashboard uses auth endpoints:
|
||
- `/api/v1/login`, `/api/v1/tokens`, `/api/v1/me/tools`.
|
||
|
||
## Payments and Donations (Optional)
|
||
- Decide early on a processor (Stripe, Ko-fi, paypal, bitcoin/crypto) to avoid churn.
|
||
- Webhook handling must verify signatures and enforce idempotency keys.
|
||
- Store donation/subscription state with `status`, `amount`, `currency`, `provider_id`, `created_at`.
|
||
|
||
## Moderation and Abuse Reporting
|
||
- Tool detail pages require a minimal abuse report endpoint.
|
||
- Create `reports` table with `tool_id`, `reporter`, `reason`, `status`.
|
||
- Add rate limit to the report endpoint to prevent spam.
|
||
|
||
## Media and Asset Handling
|
||
- Images/screenshots stored in object storage (preferred) or a dedicated `assets/` bucket.
|
||
- Enforce size limits and content-type validation.
|
||
- Generate thumbnails for cards and lazy-load in UI.
|
||
|
||
## Caching and SEO Serving
|
||
- Public pages include ETag/Last-Modified for CDN caching.
|
||
- Dashboard pages are non-cacheable and user-specific.
|
||
- Avoid cache poisoning by varying on auth cookies.
|
||
|
||
## SEO Strategy
|
||
|
||
### Technical SEO
|
||
|
||
**URL Structure:**
|
||
```
|
||
/ # Landing page
|
||
/tools # Registry browse
|
||
/tools/{owner}/{name} # Tool detail (canonical)
|
||
/tools/{owner}/{name}/v/1.0 # Specific version
|
||
/categories/{slug} # Category listing
|
||
/docs/{section}/{page} # Documentation
|
||
/tutorials/{slug} # Tutorial pages
|
||
```
|
||
|
||
**Meta Tags (per page type):**
|
||
|
||
Landing page:
|
||
```html
|
||
<title>SmartTools - Build Custom AI Commands in YAML</title>
|
||
<meta name="description" content="Create Unix-style pipeable tools that work with any AI provider. Provider-agnostic, composable, and community-driven.">
|
||
<meta name="keywords" content="ai cli tools, yaml automation, ai commands, smarttools">
|
||
```
|
||
|
||
Tool detail page:
|
||
```html
|
||
<title>{tool-name} by {owner} - SmartTools Registry</title>
|
||
<meta name="description" content="{tool description, max 160 chars}">
|
||
```
|
||
|
||
### Structured Data (Schema.org)
|
||
|
||
**SoftwareApplication (for tools):**
|
||
```json
|
||
{
|
||
"@context": "https://schema.org",
|
||
"@type": "SoftwareApplication",
|
||
"name": "summarize",
|
||
"applicationCategory": "DeveloperApplication",
|
||
"operatingSystem": "Linux, macOS, Windows",
|
||
"author": {
|
||
"@type": "Person",
|
||
"name": "owner-name"
|
||
},
|
||
"downloadUrl": "https://registry.smarttools.dev/tools/owner/summarize",
|
||
"softwareVersion": "1.2.0",
|
||
"aggregateRating": {
|
||
"@type": "AggregateRating",
|
||
"ratingValue": "4.5",
|
||
"ratingCount": "142"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Organization (site-wide):**
|
||
```json
|
||
{
|
||
"@context": "https://schema.org",
|
||
"@type": "Organization",
|
||
"name": "SmartTools",
|
||
"url": "https://smarttools.dev",
|
||
"logo": "https://smarttools.dev/logo.png",
|
||
"sameAs": [
|
||
"https://github.com/your-org/smarttools",
|
||
"https://twitter.com/smarttools"
|
||
]
|
||
}
|
||
```
|
||
|
||
**Article (for tutorials/blog):**
|
||
```json
|
||
{
|
||
"@context": "https://schema.org",
|
||
"@type": "TechArticle",
|
||
"headline": "Getting Started with SmartTools",
|
||
"author": {"@type": "Person", "name": "Author Name"},
|
||
"datePublished": "2025-01-15",
|
||
"dateModified": "2025-01-20"
|
||
}
|
||
```
|
||
|
||
### Open Graph & Social Sharing
|
||
|
||
```html
|
||
<!-- Open Graph -->
|
||
<meta property="og:title" content="SmartTools - AI CLI Tools">
|
||
<meta property="og:description" content="Build custom AI commands...">
|
||
<meta property="og:image" content="https://smarttools.dev/og-image.png">
|
||
<meta property="og:url" content="https://smarttools.dev">
|
||
<meta property="og:type" content="website">
|
||
|
||
<!-- Twitter Card -->
|
||
<meta name="twitter:card" content="summary_large_image">
|
||
<meta name="twitter:site" content="@smarttools">
|
||
<meta name="twitter:title" content="SmartTools">
|
||
<meta name="twitter:description" content="Build custom AI commands...">
|
||
<meta name="twitter:image" content="https://smarttools.dev/twitter-card.png">
|
||
```
|
||
|
||
### Sitemap
|
||
|
||
Auto-generate `sitemap.xml`:
|
||
- All public pages
|
||
- Tool detail pages (updated on publish)
|
||
- Category pages
|
||
- Documentation pages
|
||
- Priority based on page importance
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||
<url>
|
||
<loc>https://smarttools.dev/</loc>
|
||
<priority>1.0</priority>
|
||
<changefreq>daily</changefreq>
|
||
</url>
|
||
<url>
|
||
<loc>https://smarttools.dev/tools</loc>
|
||
<priority>0.9</priority>
|
||
<changefreq>daily</changefreq>
|
||
</url>
|
||
<!-- Tool pages, docs, etc. -->
|
||
</urlset>
|
||
```
|
||
|
||
### robots.txt
|
||
|
||
```
|
||
User-agent: *
|
||
Allow: /
|
||
|
||
# Block auth pages from indexing
|
||
Disallow: /login
|
||
Disallow: /register
|
||
Disallow: /dashboard
|
||
Disallow: /api/
|
||
|
||
Sitemap: https://smarttools.dev/sitemap.xml
|
||
```
|
||
|
||
### Canonical URLs
|
||
|
||
- Each page has a single canonical URL
|
||
- Use `<link rel="canonical" href="...">` tag
|
||
- Avoid duplicate content issues
|
||
- Tool versions link to latest as canonical
|
||
|
||
### Performance for SEO
|
||
|
||
- Server-side rendering for all public pages (Flask + Jinja)
|
||
- No JavaScript required for content visibility
|
||
- Fast TTFB (< 200ms target)
|
||
- Mobile-friendly (responsive design)
|
||
- Core Web Vitals in "good" range
|
||
|
||
## Content Strategy
|
||
- Core tutorials that mirror CLI workflows.
|
||
- “Project spotlights” to showcase real usage.
|
||
- Contributor recognition (monthly spotlight).
|
||
- Announcements and changelog summaries.
|
||
- Encourage AI parsing to increase adsense revenue.
|
||
|
||
## Risks and Mitigations
|
||
- **Ad overload**: strict placement rules, no ads in registry.
|
||
- **Moderation burden and load**: Implement AI enabled moderation with flags to alert human intervention to keep things moving and simplefy maintenence.
|
||
- **Content drift**: quarterly doc reviews tied to releases.
|
||
- **Consent and tracking**: default to privacy-preserving settings.
|
||
|
||
## Phase 7 Implementation Checklist
|
||
|
||
### 7.1 Foundation & Setup
|
||
- [ ] Set up Flask project structure with blueprints
|
||
- [ ] Configure Jinja2 templates with base layout
|
||
- [ ] Integrate Tailwind CSS (build pipeline)
|
||
- [ ] Set up static asset handling (CSS, JS, images)
|
||
- [ ] Configure development/production environments
|
||
- [ ] Set up database models for web-specific tables
|
||
|
||
### 7.2 Core Templates & Components
|
||
- [ ] Create base template with header/footer
|
||
- [ ] Implement navigation component (desktop + mobile)
|
||
- [ ] Build reusable card components (tool, tutorial, contributor)
|
||
- [ ] Create form components (inputs, buttons, dropdowns)
|
||
- [ ] Implement callout/alert components
|
||
- [ ] Build code block component with copy functionality
|
||
- [ ] Create loading states (skeleton, spinner)
|
||
- [ ] Implement responsive grid system
|
||
|
||
### 7.3 Landing Page
|
||
- [ ] Hero section with install snippet
|
||
- [ ] Three pillars section (Easy, Powerful, Community)
|
||
- [ ] Featured tools grid (API integration)
|
||
- [ ] Getting started tutorial cards
|
||
- [ ] Featured contributor spotlight
|
||
- [ ] Footer with links and optional ad zone
|
||
|
||
### 7.4 Registry Pages (Ad-Free)
|
||
- [ ] Tool browse page with search bar
|
||
- [ ] Category dropdown filter
|
||
- [ ] Sort options (popular, recent, name)
|
||
- [ ] Pagination component
|
||
- [ ] Tool card grid layout
|
||
- [ ] Tool detail page with README rendering
|
||
- [ ] Version selector in sidebar
|
||
- [ ] Install command with copy
|
||
- [ ] Report abuse button/modal
|
||
- [ ] Category pages
|
||
|
||
### 7.5 Documentation & Tutorials
|
||
- [ ] Docs landing page with section links
|
||
- [ ] Tutorial listing page
|
||
- [ ] Content page template with TOC
|
||
- [ ] Scroll-spy for TOC highlighting
|
||
- [ ] Code syntax highlighting (Prism/Highlight.js)
|
||
- [ ] Video embed component (YouTube)
|
||
- [ ] Related articles section
|
||
- [ ] Sidebar ad placement (desktop only)
|
||
|
||
### 7.6 Authentication & Dashboard
|
||
- [ ] Registration page and flow
|
||
- [ ] Login page with error handling
|
||
- [ ] Password reset flow (if implementing)
|
||
- [ ] Session management (cookies, CSRF)
|
||
- [ ] Dashboard layout with sidebar
|
||
- [ ] My Tools tab with tool list
|
||
- [ ] API Tokens tab with create/revoke
|
||
- [ ] Settings tab with profile edit
|
||
- [ ] Logout functionality
|
||
|
||
### 7.7 Privacy & Consent
|
||
- [ ] Cookie consent banner
|
||
- [ ] Consent preferences modal
|
||
- [ ] Consent state storage
|
||
- [ ] Privacy policy page
|
||
- [ ] Terms of service page
|
||
- [ ] Honor consent in analytics/ad loading
|
||
|
||
### 7.8 Ads & Monetization
|
||
- [ ] AdSense integration (account setup)
|
||
- [ ] Ad container components
|
||
- [ ] Lazy loading for ad scripts
|
||
- [ ] Ad placement rules enforcement
|
||
- [ ] Sponsored content styling (if applicable)
|
||
- [ ] Donate page with donation options
|
||
|
||
### 7.9 SEO & Performance
|
||
- [ ] Meta tags for all page types
|
||
- [ ] Open Graph tags
|
||
- [ ] Schema.org structured data
|
||
- [ ] Sitemap generation
|
||
- [ ] robots.txt configuration
|
||
- [ ] Canonical URL implementation
|
||
- [ ] Image optimization pipeline
|
||
- [ ] CSS/JS minification
|
||
- [ ] Critical CSS inlining
|
||
- [ ] Lazy loading for images
|
||
|
||
### 7.10 Testing & QA
|
||
- [ ] Responsive design testing (all breakpoints)
|
||
- [ ] Accessibility testing (WCAG 2.1 AA)
|
||
- [ ] Cross-browser testing (Chrome, Firefox, Safari, Edge)
|
||
- [ ] Performance testing (Lighthouse scores)
|
||
- [ ] Form validation testing
|
||
- [ ] Error state testing
|
||
- [ ] Mobile usability testing
|
||
|
||
### 7.11 Launch Preparation
|
||
- [ ] Content creation (initial docs, tutorials)
|
||
- [ ] Seed featured tools selection
|
||
- [ ] Initial contributor spotlight
|
||
- [ ] Analytics setup (privacy-respecting)
|
||
- [ ] Error monitoring (Sentry or similar)
|
||
- [ ] SSL certificate configuration
|
||
- [ ] CDN setup (optional)
|
||
- [ ] Backup and recovery procedures
|
||
|
||
## API Endpoints for Web UI
|
||
|
||
The web UI consumes these existing API endpoints:
|
||
|
||
**Public (read-only):**
|
||
- `GET /api/v1/tools` - List tools with pagination/filters
|
||
- `GET /api/v1/tools/search?q=...` - Search tools
|
||
- `GET /api/v1/tools/{owner}/{name}` - Tool details
|
||
- `GET /api/v1/tools/{owner}/{name}/versions` - Version list
|
||
- `GET /api/v1/categories` - Category list
|
||
- `GET /api/v1/stats/popular` - Popular tools
|
||
|
||
**Authenticated (dashboard):**
|
||
- `POST /api/v1/login` - User login (returns session)
|
||
- `POST /api/v1/register` - User registration
|
||
- `GET /api/v1/me/tools` - User's published tools
|
||
- `GET /api/v1/tokens` - User's API tokens
|
||
- `POST /api/v1/tokens` - Create new token
|
||
- `DELETE /api/v1/tokens/{id}` - Revoke token
|
||
- `PUT /api/v1/me/settings` - Update profile
|
||
|
||
**New endpoints for web UI:**
|
||
- `GET /api/v1/featured/tools` - Curated featured tools
|
||
- `GET /api/v1/featured/contributors` - Featured contributor
|
||
- `GET /api/v1/content/announcements` - Site announcements
|
||
- `POST /api/v1/reports` - Abuse report submission
|
||
|
||
## Diagram References
|
||
|
||
- Landing page mockup: `discussions/diagrams/smarttools-registry_rob_6.svg`
|
||
- System overview: `discussions/diagrams/smarttools-registry_rob_1.puml`
|
||
- Data flows: `discussions/diagrams/smarttools-registry_rob_5.puml`
|
||
- Web UI strategy: `discussions/diagrams/smarttools-web-ui-strategy.puml`
|
||
- UI visual strategy: `discussions/diagrams/smarttools-web-ui-visual-strategy.puml`
|
||
|
||
## Deployment Guide
|
||
|
||
### Requirements
|
||
|
||
- Python 3.11+
|
||
- pip/virtualenv
|
||
- SQLite 3 (included with Python)
|
||
|
||
### Quick Start (Development)
|
||
|
||
```bash
|
||
# Clone the repository
|
||
git clone https://gitea.brrd.tech/rob/SmartTools.git
|
||
cd SmartTools
|
||
|
||
# Create virtual environment
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
|
||
# Install with registry extras
|
||
pip install -e ".[registry]"
|
||
|
||
# Run the web server
|
||
python -m smarttools.web.app
|
||
```
|
||
|
||
The server will start on `http://localhost:5000`.
|
||
|
||
### Production Deployment
|
||
|
||
#### 1. Environment Variables
|
||
|
||
```bash
|
||
# Required
|
||
export SMARTTOOLS_REGISTRY_DB=/path/to/registry.db
|
||
export PORT=5050
|
||
|
||
# Optional
|
||
export SMARTTOOLS_ENV=production # Enables secure cookies
|
||
export SMARTTOOLS_SHOW_ADS=true # Enable ad placeholders
|
||
```
|
||
|
||
#### 2. Database Location
|
||
|
||
By default, the registry uses `~/.smarttools/registry.db`. For production:
|
||
|
||
```bash
|
||
# Create dedicated directory
|
||
mkdir -p /var/lib/smarttools
|
||
export SMARTTOOLS_REGISTRY_DB=/var/lib/smarttools/registry.db
|
||
```
|
||
|
||
**Note**: If using a merged filesystem (e.g., mergerfs), store the database on a single disk or in `/tmp` to avoid SQLite WAL mode issues:
|
||
|
||
```bash
|
||
export SMARTTOOLS_REGISTRY_DB=/tmp/smarttools-registry/registry.db
|
||
```
|
||
|
||
#### 3. Running with systemd
|
||
|
||
Create `/etc/systemd/system/smarttools-registry.service`:
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=SmartTools Registry Web Server
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=smarttools
|
||
WorkingDirectory=/opt/smarttools
|
||
Environment=SMARTTOOLS_REGISTRY_DB=/var/lib/smarttools/registry.db
|
||
Environment=PORT=5050
|
||
Environment=SMARTTOOLS_ENV=production
|
||
ExecStart=/opt/smarttools/venv/bin/python -m smarttools.web.app
|
||
Restart=always
|
||
RestartSec=5
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable smarttools-registry
|
||
sudo systemctl start smarttools-registry
|
||
```
|
||
|
||
#### 4. Reverse Proxy (nginx)
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name registry.smarttools.dev;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:5050;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
}
|
||
|
||
location /static {
|
||
alias /opt/smarttools/src/smarttools/web/static;
|
||
expires 1y;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5. SSL with Certbot
|
||
|
||
```bash
|
||
sudo certbot --nginx -d registry.smarttools.dev
|
||
```
|
||
|
||
### Tailwind CSS Build
|
||
|
||
The CSS is pre-built and committed. To rebuild after changes:
|
||
|
||
```bash
|
||
# Install dependencies
|
||
npm install
|
||
|
||
# Build for production
|
||
npx tailwindcss -i src/smarttools/web/static/css/input.css \
|
||
-o src/smarttools/web/static/css/main.css \
|
||
--minify
|
||
```
|
||
|
||
### Health Check
|
||
|
||
```bash
|
||
curl http://localhost:5050/api/v1/tools
|
||
# Returns: {"data":[],"meta":{"page":1,"per_page":20,"total":0,"total_pages":1}}
|
||
```
|
||
|
||
### Troubleshooting
|
||
|
||
| Issue | Solution |
|
||
|-------|----------|
|
||
| `disk I/O error` | Move database to non-merged filesystem |
|
||
| Port already in use | Change PORT environment variable |
|
||
| 500 errors | Check `/tmp/smarttools.log` for stack traces |
|
||
| Static files not loading | Verify static folder path in deployment |
|
||
|
||
## Future Considerations (Phase 8+)
|
||
|
||
- **Forum integration**: External (Discourse) or built-in discussions
|
||
- **Newsletter signup**: Email collection with double opt-in
|
||
- **A/B testing**: Hero messaging, CTA variations
|
||
- **Analytics dashboard**: Traffic insights for publishers
|
||
- **Premium features**: Private registries, enhanced analytics
|
||
- **Internationalization**: Multi-language support
|
||
- **Dark mode**: Theme toggle with persistence
|
||
- **PWA features**: Offline support, install prompt
|