@booklib/skills 1.0.0 → 1.3.0

package/microservices-patterns/examples/before.md

@@ -0,0 +1,40 @@
+# Before
+
+An `InventoryService` that directly queries the `orders` database table owned by another service, creating tight coupling and a shared-database anti-pattern.
+
+```java
+@RestController
+@RequestMapping("/inventory")
+public class InventoryController {
+
+    @Autowired
+    private DataSource sharedDataSource; // connected to the orders DB
+
+    @GetMapping("/reorder-candidates")
+    public List<ReorderItem> getReorderCandidates() {
+        List<ReorderItem> candidates = new ArrayList<>();
+
+        // Directly querying the Order Service's database table
+        try (Connection conn = sharedDataSource.getConnection();
+             PreparedStatement ps = conn.prepareStatement(
+                 "SELECT product_id, SUM(quantity) as sold_qty " +
+                 "FROM orders.order_lines " +
+                 "WHERE created_at > NOW() - INTERVAL 7 DAY " +
+                 "GROUP BY product_id")) {
+
+            ResultSet rs = ps.executeQuery();
+            while (rs.next()) {
+                String productId = rs.getString("product_id");
+                int soldQty = rs.getInt("sold_qty");
+                int stockLevel = getStockLevel(productId);
+                if (stockLevel < soldQty * 2) {
+                    candidates.add(new ReorderItem(productId, soldQty * 3 - stockLevel));
+                }
+            }
+        } catch (SQLException e) {
+            throw new RuntimeException(e);
+        }
+        return candidates;
+    }
+}
+```

package/microservices-patterns/scripts/new_service.py

@@ -0,0 +1,583 @@
+#!/usr/bin/env python3
+"""
+Microservice Scaffold — generates a new microservice skeleton with proper boundaries.
+
+Usage: python new_service.py <ServiceName> [--lang python|java|kotlin] [--output-dir ./]
+
+Generates a service with:
+  - Its own domain model (no shared DB)
+  - Event publishing stub
+  - Health endpoint
+  - README with responsibility and run instructions
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from string import Template
+
+# ---------------------------------------------------------------------------
+# Name helpers
+# ---------------------------------------------------------------------------
+
+def to_snake(name: str) -> str:
+    """PascalCase -> snake_case, e.g. OrderService -> order_service"""
+    s = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+    s = re.sub(r"([a-z\d])([A-Z])", r"\1_\2", s)
+    return s.lower()
+
+
+def to_kebab(name: str) -> str:
+    return to_snake(name).replace("_", "-")
+
+
+def strip_service(name: str) -> str:
+    """Remove trailing 'Service' suffix for entity naming."""
+    return re.sub(r"Service$", "", name, flags=re.IGNORECASE)
+
+
+# ---------------------------------------------------------------------------
+# Python templates
+# ---------------------------------------------------------------------------
+
+PY_MAIN = Template("""\
+#!/usr/bin/env python3
+\"\"\"Entry point for the $service_name microservice.\"\"\"
+import uvicorn
+
+if __name__ == "__main__":
+    uvicorn.run("app.api.routes:app", host="0.0.0.0", port=8000, reload=False)
+""")
+
+PY_ROUTES = Template("""\
+\"\"\"FastAPI routes for $service_name.\"\"\"
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from ..domain.${entity_snake} import ${Entity}, ${Entity}Id
+from ..domain.${entity_snake}_repository import ${Entity}Repository
+from ..infrastructure.in_memory_repository import InMemory${Entity}Repository
+from ..infrastructure.event_publisher import EventPublisher
+
+app = FastAPI(title="$service_name", version="0.1.0")
+
+# In production replace with real DI / IOC.
+_repo: ${Entity}Repository = InMemory${Entity}Repository()
+_publisher = EventPublisher()
+
+
+class Create${Entity}Request(BaseModel):
+    name: str
+
+
+class ${Entity}Response(BaseModel):
+    id: str
+    name: str
+
+
+@app.get("/healthz")
+def health() -> dict:
+    return {"status": "ok", "service": "$service_name"}
+
+
+@app.post("/${entity_kebab}s", response_model=${Entity}Response, status_code=201)
+def create_${entity_snake}(req: Create${Entity}Request) -> ${Entity}Response:
+    entity = ${Entity}.create(name=req.name)
+    _repo.save(entity)
+    for event in entity.pull_events():
+        _publisher.publish(event)
+    return ${Entity}Response(id=str(entity.id), name=entity.name)
+
+
+@app.get("/${entity_kebab}s/{id}", response_model=${Entity}Response)
+def get_${entity_snake}(id: str) -> ${Entity}Response:
+    entity = _repo.find_by_id(${Entity}Id(id))
+    if entity is None:
+        raise HTTPException(status_code=404, detail="${Entity} not found")
+    return ${Entity}Response(id=str(entity.id), name=entity.name)
+""")
+
+PY_ENTITY = Template("""\
+\"\"\"Domain entity for $Entity — $service_name aggregate root.\"\"\"
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import List
+import uuid
+
+
+@dataclass(frozen=True)
+class ${Entity}Id:
+    value: str
+
+    def __post_init__(self) -> None:
+        if not self.value:
+            raise ValueError("${Entity}Id must not be blank.")
+
+    @classmethod
+    def generate(cls) -> "${Entity}Id":
+        return cls(str(uuid.uuid4()))
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass
+class ${Entity}Event:
+    event_type: str
+    payload: dict
+
+
+@dataclass
+class ${Entity}:
+    id: ${Entity}Id
+    name: str
+    _events: List[${Entity}Event] = field(default_factory=list, init=False, repr=False)
+
+    @classmethod
+    def create(cls, name: str) -> "${Entity}":
+        if not name or not name.strip():
+            raise ValueError("name must not be blank.")
+        entity = cls(id=${Entity}Id.generate(), name=name)
+        entity._events.append(${Entity}Event("${Entity}Created", {"id": str(entity.id), "name": name}))
+        return entity
+
+    def pull_events(self) -> List[${Entity}Event]:
+        events, self._events = self._events, []
+        return events
+""")
+
+PY_REPOSITORY = Template("""\
+\"\"\"Repository interface (port) for ${Entity}.\"\"\"
+from abc import ABC, abstractmethod
+from typing import Optional
+from .${entity_snake} import ${Entity}, ${Entity}Id
+
+
+class ${Entity}Repository(ABC):
+    @abstractmethod
+    def find_by_id(self, id: ${Entity}Id) -> Optional[${Entity}]: ...
+
+    @abstractmethod
+    def save(self, entity: ${Entity}) -> None: ...
+
+    @abstractmethod
+    def delete(self, id: ${Entity}Id) -> None: ...
+""")
+
+PY_IN_MEMORY_REPO = Template("""\
+\"\"\"In-memory repository for development and testing.\"\"\"
+from typing import Dict, Optional
+from ..domain.${entity_snake} import ${Entity}, ${Entity}Id
+from ..domain.${entity_snake}_repository import ${Entity}Repository
+
+
+class InMemory${Entity}Repository(${Entity}Repository):
+    def __init__(self) -> None:
+        self._store: Dict[str, ${Entity}] = {}
+
+    def find_by_id(self, id: ${Entity}Id) -> Optional[${Entity}]:
+        return self._store.get(id.value)
+
+    def save(self, entity: ${Entity}) -> None:
+        self._store[entity.id.value] = entity
+
+    def delete(self, id: ${Entity}Id) -> None:
+        self._store.pop(id.value, None)
+""")
+
+PY_EVENT_PUBLISHER = Template("""\
+\"\"\"Event publisher stub — replace with real broker integration (Kafka, SNS, etc.).\"\"\"
+import json
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class EventPublisher:
+    \"\"\"Publishes domain events to a message broker.
+
+    In production, swap this stub with a Kafka producer, AWS SNS client,
+    RabbitMQ publisher, or similar. The interface intentionally stays simple.
+    \"\"\"
+
+    def publish(self, event: Any) -> None:
+        payload = {
+            "event_type": getattr(event, "event_type", type(event).__name__),
+            "payload": getattr(event, "payload", {}),
+        }
+        logger.info("EVENT PUBLISHED: %s", json.dumps(payload))
+        # TODO: replace with real broker call, e.g.:
+        # self._producer.produce(topic="$service_kebab-events", value=json.dumps(payload))
+""")
+
+PY_REQUIREMENTS = Template("""\
+fastapi>=0.110.0
+uvicorn[standard]>=0.29.0
+pydantic>=2.0.0
+""")
+
+PY_DOCKERFILE = Template("""\
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["python", "main.py"]
+""")
+
+PY_INIT = """\
+"""
+
+# ---------------------------------------------------------------------------
+# Java templates (single-file for brevity; split in real project)
+# ---------------------------------------------------------------------------
+
+JAVA_ENTITY = Template("""\
+package com.example.${entity_lower};
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+public final class ${Entity} {
+    private final ${Entity}Id id;
+    private String name;
+    private final List<${Entity}Event> events = new ArrayList<>();
+
+    private ${Entity}(${Entity}Id id, String name) {
+        this.id = id;
+        this.name = name;
+    }
+
+    public static ${Entity} create(String name) {
+        if (name == null || name.isBlank()) throw new IllegalArgumentException("name must not be blank");
+        var e = new ${Entity}(${Entity}Id.generate(), name);
+        e.events.add(new ${Entity}Event("${Entity}Created", java.util.Map.of("id", e.id.value(), "name", name)));
+        return e;
+    }
+
+    public ${Entity}Id getId() { return id; }
+    public String getName() { return name; }
+
+    public List<${Entity}Event> pullEvents() {
+        var copy = List.copyOf(events);
+        events.clear();
+        return copy;
+    }
+}
+""")
+
+JAVA_ID = Template("""\
+package com.example.${entity_lower};
+import java.util.UUID;
+
+public record ${Entity}Id(String value) {
+    public ${Entity}Id { if (value == null || value.isBlank()) throw new IllegalArgumentException("blank id"); }
+    public static ${Entity}Id generate() { return new ${Entity}Id(UUID.randomUUID().toString()); }
+    public static ${Entity}Id of(String s) { return new ${Entity}Id(s); }
+    @Override public String toString() { return value; }
+}
+""")
+
+JAVA_EVENT = Template("""\
+package com.example.${entity_lower};
+import java.util.Map;
+
+public record ${Entity}Event(String eventType, Map<String, Object> payload) {}
+""")
+
+JAVA_REPOSITORY = Template("""\
+package com.example.${entity_lower};
+import java.util.Optional;
+
+public interface ${Entity}Repository {
+    Optional<${Entity}> findById(${Entity}Id id);
+    void save(${Entity} entity);
+    void delete(${Entity}Id id);
+}
+""")
+
+JAVA_PUBLISHER = Template("""\
+package com.example.${entity_lower};
+
+public class EventPublisher {
+    /** Replace with Kafka / SNS / RabbitMQ integration in production. */
+    public void publish(${Entity}Event event) {
+        System.out.printf("[EVENT] type=%s payload=%s%n", event.eventType(), event.payload());
+    }
+}
+""")
+
+JAVA_MAIN = Template("""\
+package com.example.${entity_lower};
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * Minimal HTTP entry point — wire up Spring Boot / Micronaut / Quarkus in production.
+ * This stub demonstrates domain wiring only.
+ */
+public class Main {
+
+    // In-memory repo for the stub
+    static Map<String, ${Entity}> store = new HashMap<>();
+    static ${Entity}Repository repo = new ${Entity}Repository() {
+        public Optional<${Entity}> findById(${Entity}Id id) { return Optional.ofNullable(store.get(id.value())); }
+        public void save(${Entity} e) { store.put(e.getId().value(), e); }
+        public void delete(${Entity}Id id) { store.remove(id.value()); }
+    };
+    static EventPublisher publisher = new EventPublisher();
+
+    public static void main(String[] args) {
+        var entity = ${Entity}.create("Example");
+        repo.save(entity);
+        entity.pullEvents().forEach(publisher::publish);
+        System.out.println("Created: " + entity.getId());
+
+        var found = repo.findById(entity.getId());
+        found.ifPresent(e -> System.out.println("Found: " + e.getName()));
+    }
+}
+""")
+
+# ---------------------------------------------------------------------------
+# Kotlin templates
+# ---------------------------------------------------------------------------
+
+KT_ENTITY = Template("""\
+package com.example.${entity_lower}
+
+import java.util.UUID
+
+data class ${Entity}Id(val value: String) {
+    init { require(value.isNotBlank()) { "blank id" } }
+    companion object {
+        fun generate() = ${Entity}Id(UUID.randomUUID().toString())
+        fun of(s: String) = ${Entity}Id(s)
+    }
+    override fun toString() = value
+}
+
+data class ${Entity}Event(val eventType: String, val payload: Map<String, Any>)
+
+class ${Entity} private constructor(val id: ${Entity}Id, val name: String) {
+    private val _events = mutableListOf<${Entity}Event>()
+
+    companion object {
+        fun create(name: String): ${Entity} {
+            require(name.isNotBlank()) { "name must not be blank" }
+            val e = ${Entity}(${Entity}Id.generate(), name)
+            e._events.add(${Entity}Event("${Entity}Created", mapOf("id" to e.id.value, "name" to name)))
+            return e
+        }
+    }
+
+    fun pullEvents(): List<${Entity}Event> {
+        val copy = _events.toList(); _events.clear(); return copy
+    }
+}
+""")
+
+KT_REPOSITORY = Template("""\
+package com.example.${entity_lower}
+
+interface ${Entity}Repository {
+    fun findById(id: ${Entity}Id): ${Entity}?
+    fun save(entity: ${Entity})
+    fun delete(id: ${Entity}Id)
+}
+
+class InMemory${Entity}Repository : ${Entity}Repository {
+    private val store = mutableMapOf<String, ${Entity}>()
+    override fun findById(id: ${Entity}Id) = store[id.value]
+    override fun save(entity: ${Entity}) { store[entity.id.value] = entity }
+    override fun delete(id: ${Entity}Id) { store.remove(id.value) }
+}
+""")
+
+KT_PUBLISHER = Template("""\
+package com.example.${entity_lower}
+
+class EventPublisher {
+    /** Replace with Kafka / SNS / RabbitMQ integration in production. */
+    fun publish(event: ${Entity}Event) {
+        println("[EVENT] type=${dollar}{event.eventType} payload=${dollar}{event.payload}")
+    }
+}
+""")
+
+KT_MAIN = Template("""\
+package com.example.${entity_lower}
+
+fun main() {
+    val repo: ${Entity}Repository = InMemory${Entity}Repository()
+    val publisher = EventPublisher()
+
+    val entity = ${Entity}.create("Example")
+    repo.save(entity)
+    entity.pullEvents().forEach { publisher.publish(it) }
+
+    println("Created: ${dollar}{entity.id}")
+    println("Found:   ${dollar}{repo.findById(entity.id)?.name}")
+}
+""")
+
+README = Template("""\
+# $service_name
+
+## Responsibility
+
+> **$service_name** is responsible for managing the lifecycle of `$Entity` resources.
+> It owns its own data store and publishes domain events when state changes occur.
+
+This service follows the microservices pattern of **one service, one bounded context**.
+It does **not** share a database with any other service.
+
+## Structure
+
+```
+$service_dir/
+├── app/
+│   ├── api/          # HTTP layer (routes, request/response models)
+│   ├── domain/       # Entities, value objects, repository interfaces
+│   └── infrastructure/   # Concrete adapters (DB, cache, event broker)
+├── main.py           # Entry point
+├── requirements.txt
+├── Dockerfile
+└── README.md
+```
+
+## Running Locally
+
+```bash
+pip install -r requirements.txt
+python main.py
+# or:
+uvicorn app.api.routes:app --reload
+```
+
+Open http://localhost:8000/docs for the interactive API documentation.
+
+## Events Published
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `${Entity}Created` | POST /${entity_kebab}s | `{id, name}` |
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `8000` | HTTP listen port |
+| `DATABASE_URL` | in-memory | Connection string for the DB adapter |
+| `BROKER_URL` | stdout | Event broker endpoint |
+
+## Design Decisions
+
+- **No shared database**: Other services must call this service's API or consume its events.
+- **Event publishing**: Every state change emits a domain event for downstream consumers.
+- **Repository pattern**: The domain layer depends on an interface; the infrastructure layer provides the adapter.
+""")
+
+
+# ---------------------------------------------------------------------------
+# Writer
+# ---------------------------------------------------------------------------
+
+def write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    print(f"  Created: {path}")
+
+
+def scaffold_python(service_dir: Path, ctx: dict) -> None:
+    base = service_dir
+    write(base / "main.py", PY_MAIN.substitute(ctx))
+    write(base / "requirements.txt", PY_REQUIREMENTS.substitute(ctx))
+    write(base / "Dockerfile", PY_DOCKERFILE.substitute(ctx))
+    write(base / "app" / "__init__.py", PY_INIT)
+    write(base / "app" / "api" / "__init__.py", PY_INIT)
+    write(base / "app" / "api" / "routes.py", PY_ROUTES.substitute(ctx))
+    write(base / "app" / "domain" / "__init__.py", PY_INIT)
+    write(base / "app" / "domain" / f"{ctx['entity_snake']}.py", PY_ENTITY.substitute(ctx))
+    write(base / "app" / "domain" / f"{ctx['entity_snake']}_repository.py", PY_REPOSITORY.substitute(ctx))
+    write(base / "app" / "infrastructure" / "__init__.py", PY_INIT)
+    write(base / "app" / "infrastructure" / "in_memory_repository.py", PY_IN_MEMORY_REPO.substitute(ctx))
+    write(base / "app" / "infrastructure" / "event_publisher.py", PY_EVENT_PUBLISHER.substitute(ctx))
+
+
+def scaffold_java(service_dir: Path, ctx: dict) -> None:
+    pkg = service_dir / "src" / "main" / "java" / "com" / "example" / ctx["entity_lower"]
+    write(pkg / f"{ctx['Entity']}.java", JAVA_ENTITY.substitute(ctx))
+    write(pkg / f"{ctx['Entity']}Id.java", JAVA_ID.substitute(ctx))
+    write(pkg / f"{ctx['Entity']}Event.java", JAVA_EVENT.substitute(ctx))
+    write(pkg / f"{ctx['Entity']}Repository.java", JAVA_REPOSITORY.substitute(ctx))
+    write(pkg / "EventPublisher.java", JAVA_PUBLISHER.substitute(ctx))
+    write(pkg / "Main.java", JAVA_MAIN.substitute(ctx))
+
+
+def scaffold_kotlin(service_dir: Path, ctx: dict) -> None:
+    pkg = service_dir / "src" / "main" / "kotlin" / "com" / "example" / ctx["entity_lower"]
+    write(pkg / f"{ctx['Entity']}.kt", KT_ENTITY.substitute(ctx))
+    write(pkg / f"{ctx['Entity']}Repository.kt", KT_REPOSITORY.substitute(ctx))
+    write(pkg / "EventPublisher.kt", KT_PUBLISHER.substitute(ctx))
+    write(pkg / "Main.kt", KT_MAIN.substitute(ctx))
+
+
+SCAFFOLDERS = {"python": scaffold_python, "java": scaffold_java, "kotlin": scaffold_kotlin}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Scaffold a microservice skeleton.")
+    parser.add_argument("service_name", metavar="ServiceName",
+                        help="Service name in PascalCase, e.g. OrderService")
+    parser.add_argument("--lang", choices=["python", "java", "kotlin"], default="python")
+    parser.add_argument("--output-dir", default=".", type=Path)
+    args = parser.parse_args()
+
+    name = args.service_name
+    entity = strip_service(name)
+    service_dir = args.output_dir / to_kebab(name)
+
+    ctx = {
+        "service_name": name,
+        "service_kebab": to_kebab(name),
+        "service_dir": to_kebab(name),
+        "Entity": entity,
+        "entity_snake": to_snake(entity),
+        "entity_lower": entity.lower(),
+        "entity_kebab": to_kebab(entity),
+        "dollar": "$",
+    }
+
+    print(f"\nScaffolding microservice '{name}' ({args.lang}) in {service_dir}/\n")
+    SCAFFOLDERS[args.lang](service_dir, ctx)
+    write(service_dir / "README.md", README.substitute(ctx))
+
+    print(f"\nDone. Next steps:")
+    if args.lang == "python":
+        print(f"  cd {service_dir}")
+        print(f"  pip install -r requirements.txt")
+        print(f"  python main.py")
+        print(f"  # API docs: http://localhost:8000/docs")
+    elif args.lang == "java":
+        print(f"  cd {service_dir}")
+        print(f"  # Add to a Maven/Gradle project, then: mvn compile exec:java -Dexec.mainClass=com.example.{entity.lower()}.Main")
+    elif args.lang == "kotlin":
+        print(f"  cd {service_dir}")
+        print(f"  # Add to a Gradle project, then: ./gradlew run")
+    print(f"\n  Replace InMemory{entity}Repository with a real DB adapter.")
+    print(f"  Replace EventPublisher stub with a Kafka/SNS producer.\n")
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@booklib/skills",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "description": "Book knowledge distilled into structured AI skills for Claude Code and other AI assistants",
   "bin": {
     "skills": "./bin/skills.js"

package/refactoring-ui/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-poor-visual-hierarchy",
+      "prompt": "Review this CSS for a product card component:\n\n```css\n.product-card {\n  padding: 20px;\n  border: 1px solid #cccccc;\n  border-radius: 4px;\n  background: white;\n}\n\n.product-card .category-label {\n  font-size: 16px;\n  font-weight: 400;\n  color: #333333;\n  margin-bottom: 8px;\n}\n\n.product-card .product-name {\n  font-size: 18px;\n  font-weight: 400;\n  color: #333333;\n  margin-bottom: 8px;\n}\n\n.product-card .product-price {\n  font-size: 16px;\n  font-weight: 400;\n  color: #333333;\n  margin-bottom: 8px;\n}\n\n.product-card .product-description {\n  font-size: 15px;\n  font-weight: 400;\n  color: #333333;\n  margin-bottom: 12px;\n}\n\n.product-card .stock-status {\n  font-size: 14px;\n  font-weight: 400;\n  color: #333333;\n}\n\n.product-card .add-to-cart-btn {\n  font-size: 16px;\n  font-weight: 400;\n  background: #333333;\n  color: white;\n  padding: 10px 20px;\n  border: none;\n  border-radius: 4px;\n  margin-top: 12px;\n}\n```",
+      "expectations": [
+        "Identifies the core problem: visual hierarchy is flat — nearly every element uses the same font-size (15-18px) and font-weight (400), making it impossible to identify what matters most at a glance",
+        "Flags that the product name should be the most visually prominent element — it should use a larger size (24-30px) and heavier weight (600-700) to create a clear entry point",
+        "Flags that the price is the second most important element — it should be visually distinct, not the same weight as the description",
+        "Points out that category-label should be de-emphasized (smaller, lighter color like hsl(0,0%,55%)) — it is supporting context, not primary information",
+        "Notes that relying on font-size alone for hierarchy is addressed in Chapter 2 of Refactoring UI: use weight and color as primary levers, size as secondary",
+        "Flags that all elements use the same color (#333333) — tertiary elements like category-label and stock-status should use a lighter grey to create visual separation",
+        "Notes the add-to-cart button has font-weight: 400 — a primary action button should use font-weight 500-600 for emphasis",
+        "Recommends a concrete hierarchy: product-name (24px, 700 weight, dark), price (20px, 600 weight, dark), description (15px, 400 weight, medium grey #6b7280), category-label (12px, 500 weight, uppercase, light grey)"
+      ]
+    },
+    {
+      "id": "eval-02-too-many-colors-no-spacing-system",
+      "prompt": "Review this CSS for a dashboard sidebar:\n\n```css\n.sidebar {\n  background: #1a237e;\n  padding: 15px;\n  width: 240px;\n}\n\n.sidebar-header {\n  color: #ffffff;\n  font-size: 22px;\n  margin-bottom: 7px;\n  padding-bottom: 11px;\n  border-bottom: 2px solid #3949ab;\n}\n\n.nav-item {\n  color: #b0bec5;\n  font-size: 14px;\n  padding: 9px 13px;\n  margin-bottom: 3px;\n  border-radius: 6px;\n}\n\n.nav-item.active {\n  background: #ff6f00;\n  color: #ffffff;\n}\n\n.nav-item:hover {\n  background: #283593;\n  color: #e8eaf6;\n}\n\n.nav-section-label {\n  color: #ffd54f;\n  font-size: 11px;\n  text-transform: uppercase;\n  margin-top: 18px;\n  margin-bottom: 6px;\n  letter-spacing: 1px;\n}\n\n.badge {\n  background: #e53935;\n  color: white;\n  font-size: 10px;\n  padding: 2px 7px;\n  border-radius: 10px;\n}\n\n.sidebar-footer {\n  margin-top: 23px;\n  padding-top: 14px;\n  border-top: 1px solid #303f9f;\n  color: #90a4ae;\n  font-size: 13px;\n}\n```",
+      "expectations": [
+        "Identifies the color proliferation problem: #1a237e, #3949ab, #ff6f00, #b0bec5, #283593, #e8eaf6, #ffd54f, #e53935, #303f9f, #90a4ae — 10+ ad-hoc hex colors with no systematic relationship",
+        "Flags that the active state uses #ff6f00 (deep orange) which is unrelated to the #1a237e (indigo) background — the accent color should be a lighter tint of the primary palette or a purposeful brand color",
+        "Flags that nav-section-label uses #ffd54f (amber/yellow) as a color — this creates a third unrelated hue in the sidebar; section labels should use a desaturated light color consistent with the palette",
+        "Flags the arbitrary spacing values: 7px, 11px, 9px, 13px, 3px, 18px, 6px, 23px, 14px — none of these follow a spacing scale; Refactoring UI Ch 3 prescribes a constrained scale (4, 8, 12, 16, 24, 32px)",
+        "Notes that grey-on-deep-blue text (#b0bec5 on #1a237e) needs a contrast check — and recommends using a color that is hue-matched to the background rather than a neutral grey",
+        "Recommends defining a design token set: 2-3 shades of indigo for the sidebar tones, one accent color for the active state, one semantic red for the badge — not 10 unrelated hex values",
+        "Notes that the badge using an unrelated red (#e53935) is fine for semantic meaning but should be defined as a token (--color-danger) rather than a hard-coded hex"
+      ]
+    },
+    {
+      "id": "eval-03-clean-hierarchy-design",
+      "prompt": "Review this CSS for a pricing card component:\n\n```css\n:root {\n  --space-1: 4px;\n  --space-2: 8px;\n  --space-3: 12px;\n  --space-4: 16px;\n  --space-6: 24px;\n  --space-8: 32px;\n  --space-12: 48px;\n\n  --text-sm: 13px;\n  --text-base: 16px;\n  --text-lg: 18px;\n  --text-xl: 20px;\n  --text-3xl: 30px;\n\n  --color-text-primary: hsl(222, 47%, 11%);\n  --color-text-secondary: hsl(215, 20%, 40%);\n  --color-text-tertiary: hsl(215, 16%, 60%);\n  --color-accent: hsl(245, 75%, 60%);\n  --color-accent-light: hsl(245, 75%, 96%);\n}\n\n.pricing-card {\n  background: white;\n  border-radius: 12px;\n  padding: var(--space-8);\n  box-shadow: 0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06);\n  max-width: 320px;\n}\n\n.plan-name {\n  font-size: var(--text-sm);\n  font-weight: 600;\n  color: var(--color-accent);\n  text-transform: uppercase;\n  letter-spacing: 0.08em;\n  margin-bottom: var(--space-3);\n}\n\n.plan-price {\n  font-size: var(--text-3xl);\n  font-weight: 700;\n  color: var(--color-text-primary);\n  margin-bottom: var(--space-1);\n}\n\n.price-period {\n  font-size: var(--text-sm);\n  color: var(--color-text-tertiary);\n  margin-bottom: var(--space-6);\n}\n\n.feature-list {\n  list-style: none;\n  padding: 0;\n  margin: 0 0 var(--space-8) 0;\n}\n\n.feature-item {\n  font-size: var(--text-base);\n  color: var(--color-text-secondary);\n  padding: var(--space-2) 0;\n  display: flex;\n  align-items: center;\n  gap: var(--space-3);\n}\n\n.cta-button {\n  display: block;\n  width: 100%;\n  padding: var(--space-3) var(--space-6);\n  background: var(--color-accent);\n  color: white;\n  font-size: var(--text-base);\n  font-weight: 600;\n  border: none;\n  border-radius: 8px;\n  cursor: pointer;\n  text-align: center;\n}\n```",
+      "expectations": [
+        "Recognizes this as a well-designed component with proper design system foundations and says so explicitly",
+        "Praises the CSS custom property (design token) system: spacing scale (--space-1 through --space-12 in steps of 4px), type scale (--text-sm through --text-3xl), and color tokens all follow Refactoring UI principles",
+        "Praises the three-level color hierarchy for text: --color-text-primary (dark), --color-text-secondary (medium), --color-text-tertiary (light) — directly implementing the Refactoring UI color-as-hierarchy approach",
+        "Praises the visual hierarchy of the price card: plan name is small+uppercase+accent (supporting), price is 30px+700 weight (primary), period is small+tertiary (de-emphasized) — excellent three-tier hierarchy",
+        "Praises the shadow: uses a two-layer shadow (diffuse + tight) following the Refactoring UI recommendation for realistic depth",
+        "Praises that plan-name uses color (--color-accent) to create emphasis at a small size rather than making it large — using color+weight as levers, not font-size alone",
+        "Does NOT manufacture fake issues just to have something to say",
+        "May offer optional improvements (hover state for cta-button, dark mode token variants, focus ring for accessibility) but clearly frames them as enhancements"
+      ]
+    }
+  ]
+}