smarttools/docs/WEB_UI.md

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:

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

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

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

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

<button class="btn-ghost">Read More</button>

• Background: Transparent
• Text: Primary indigo
• Hover: Light indigo background

Danger Button:

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

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

<span class="badge badge-category">text-processing</span>

• Background: Cyan (#06B6D4)
• Text: White, 12px
• Padding: 4px 8px
• Border-radius: 4px

Tag:

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

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

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

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

<title>{tool-name} by {owner} - SmartTools Registry</title>
<meta name="description" content="{tool description, max 160 chars}">

Structured Data (Schema.org)

SoftwareApplication (for tools):

{
  "@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):

{
  "@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):

{
  "@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

<!-- 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 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)

# 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

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

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

export SMARTTOOLS_REGISTRY_DB=/tmp/smarttools-registry/registry.db

3. Running with systemd

Create /etc/systemd/system/smarttools-registry.service:

[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

sudo systemctl daemon-reload
sudo systemctl enable smarttools-registry
sudo systemctl start smarttools-registry

4. Reverse Proxy (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

sudo certbot --nginx -d registry.smarttools.dev

Tailwind CSS Build

The CSS is pre-built and committed. To rebuild after changes:

# 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

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