AI Resource Detail Page - Score-Driven Architecture¶

📋 Overview¶

This document describes the information architecture redesign for AI resource detail pages, elevating Overall Status Score from supporting metadata to a primary decision signal.

Core Principle: Users should be able to determine if a resource is worth exploring within 3 seconds of landing on the page.

🎯 Design Goals¶

1. Reduce Cognitive Load: Present the key decision factor (score) immediately and prominently
2. Maintain Information Density: Reorganize, don't remove existing content
3. Establish Behavioral Consistency: Same score always yields same recommendation across the site
4. Enable Quality Navigation: Related resources guide users toward equal or higher quality content

📐 Information Architecture¶

1. Judgement Header (New Primary Section)¶

Location: Immediately below resource title and description

Components:

• Overall Score (75/100 format)
• Progress bar visualization
• Status badge (Excellent/Good/Fair/Early/Caution)
• One-sentence summary recommendation

Implementation:

• Template: layouts/partials/ai-judgement-header.html
• Styles: assets/scss/layouts/ai/_ai-judgement-header.scss
• JavaScript: assets/js/ai-judgement-header.js

Example:

[Next AI Draw.io]
[Brief description...]

┌─────────────────────────────────────────────────┐
│  75 / 100  ████████████░░░░  Fair              │
│  Worth Trying · Active but early-stage          │
└─────────────────────────────────────────────────┘

2. Score Breakdown Card (Refactored Sidebar)¶

Previously: "Resource Info" (混合了结论和证据) Now: "Score Breakdown" (纯证据展示)

Content Order (Fixed sequence):

1. Overall Status (repeated, smaller)
2. Four-dimensional scores (Activity/Community/Impact/Sustainability)
3. Last Update timestamp
4. Smart badges (Popular/Active/Fast Growing)

Changes:

• Removed explanatory text
• Reduced visual weight compared to main judgement header
• Reordered to prioritize score metrics

3. Score Semantic System¶

Score Range Mapping (Hardcoded in config):

Configuration: data/score-ranges.yaml

Usage:

• Generates main judgement summary
• Determines visual styling (colors, badges)
• Guides related resource sorting
• Future: List page filters and sort options

4. Related Resources Enhancement¶

Previous Logic: Content similarity (author/category/tags)

New Logic:

1. Fetch scores for all related resources
2. Prioritize resources with score ≥ current page's score
3. Within each tier, sort by score descending

Implementation: assets/js/ai-related-resources.js

Goal: Users clicking through related resources experience consistent or improving quality

🗂️ File Structure¶

data/
  └── score-ranges.yaml           # Score semantic mapping

layouts/
  ├── ai/
  │   └── single.html             # Updated with judgement header
  └── partials/
      └── ai-judgement-header.html  # New judgement component

assets/
  ├── scss/layouts/ai/
  │   ├── _ai.scss                # Updated imports
  │   └── _ai-judgement-header.scss  # New styles
  └── js/
      ├── ai-judgement-header.js  # Score display logic
      └── ai-related-resources.js # Score-based sorting

i18n/
  ├── en.yaml                     # New translation keys
  └── zh.yaml                     # New translation keys

🌐 Internationalization¶

New i18n keys added:

# Judgement Header
- id: ai_score_breakdown
  translation: Score Breakdown
- id: ai_loading_score
  translation: Loading score...
- id: ai_score_unavailable
  translation: Score data unavailable

🎨 Visual Design¶

Judgement Header Styling¶

• Background: Subtle gradient (blue to green, 5% opacity)
• Border: Dynamic color based on score range
• Score Number: Large (2.5rem), primary color, tabular numerals
• Progress Bar: 8px height, gradient fill matching score
• Status Badge: Color-coded by range, uppercase, 600 weight

Responsive Behavior¶

• Desktop: Horizontal layout, score on left, labels on right
• Mobile: Stacked layout, full-width progress bar
• Print: Simplified grayscale version

📊 Data Flow¶

1. Page Load
   ↓
2. Render static content (title, description, buttons)
   ↓
3. JavaScript: Fetch health data from Worker API
   ↓
4. Calculate overall score
   ↓
5. Map score to semantic range
   ↓
6. Populate judgement header (score, bar, badge, summary)
   ↓
7. Populate score breakdown card
   ↓
8. Fetch scores for related resources
   ↓
9. Re-sort related resources by score

Caching: 30-minute session storage cache for all API calls

✅ Validation Criteria¶

A successful implementation meets these requirements:

1. ✅ Above the fold: Score visible without scrolling on desktop
2. ✅ Quick comprehension: User can assess value without reading full content
3. ✅ Clear hierarchy: Main judgement header visually dominant over sidebar
4. ✅ Consistency: Same score produces identical label/summary across all pages
5. ✅ Quality preservation: Related resource suggestions maintain or improve quality
6. ✅ Graceful degradation: Handles missing data (no GitHub, no score) cleanly

🔄 Future Enhancements¶

Phase 2: List Page Integration¶

Add to AI resources list page:

• sort=score_desc URL parameter
• filter=score_range[70-100] filtering
• Score badge in card view
• Score column in table view

Phase 3: Recommendation System¶

• Score-based content recommendations on homepage
• Email digest with high-scoring recent additions
• "Similar but higher-rated" suggestions

🚫 Anti-Patterns to Avoid¶

1. Don't use score as the only consideration (content relevance still matters)
2. Don't over-animate the judgement header (keep it professional)
3. Don't hide the score behind clicks or tabs
4. Don't show conflicting recommendations (main header vs sidebar)
5. Don't assume all resources have scores (handle missing data gracefully)

📝 Changelog¶

2025-01-18: Initial Implementation¶

• Created judgement header component and styling
• Refactored sidebar from "Resource Info" to "Score Breakdown"
• Implemented score semantic mapping system
• Enhanced related resources with score-based sorting
• Added internationalization support (en/zh)

🎓 Design Philosophy¶

"This page is not a neutral directory. It is an editor-curated AI resource index. Overall score is a primary decision signal and must appear in the main reading flow, not as metadata."

This architecture treats resource quality as a first-class citizen in the information hierarchy, not an afterthought or supplementary detail. Users deserve immediate clarity about whether a resource merits their time and attention.