# 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`

## 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
