# 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
```
- 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
```
- Background: Transparent
- Border: 2px solid cyan (#06B6D4)
- Text: Cyan, 16px, font-weight 600
- Hover: Light cyan background (#ECFEFF)
**Ghost Button:**
```html
```
- Background: Transparent
- Text: Primary indigo
- Hover: Light indigo background
**Danger Button:**
```html
```
- 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
```
- 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
text-processing
```
- Background: Cyan (#06B6D4)
- Text: White, 12px
- Padding: 4px 8px
- Border-radius: 4px
**Tag:**
```html
ai
```
- Background: Light gray (#F3F4F6)
- Text: Secondary gray, 12px
- Border: 1px solid border color
- Border-radius: 9999px (pill)
- Clickable (links to search)
**Status Badge:**
```html
Published
Pending
Yanked
```
- Success: Green background
- Warning: Amber background
- Error: Red background
### Code Blocks
**Inline Code:**
```html
smarttools run foo
```
- 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 ``)
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
SmartTools - Build Custom AI Commands in YAML
```
Tool detail page:
```html
{tool-name} by {owner} - SmartTools Registry
```
### 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
```
### Sitemap
Auto-generate `sitemap.xml`:
- All public pages
- Tool detail pages (updated on publish)
- Category pages
- Documentation pages
- Priority based on page importance
```xml
https://smarttools.dev/
1.0
daily
https://smarttools.dev/tools
0.9
daily
```
### 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 `` 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