@booklib/core 2.0.0

package/skills/refactoring-ui/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: refactoring-ui
+version: "1.0"
+license: MIT
+tags: [ui, design, css, frontend]
+description: >
+  Apply UI design principles from Refactoring UI by Adam Wathan & Steve Schoger.
+  Covers visual hierarchy (size, weight, color, spacing), layout systems (spacing
+  scales, grids), typography (type scales, line-height, alignment), color (HSL
+  palettes, shade systems, accessible contrast), depth (shadow elevation, overlap),
+  images (text on images, user content, icons), and finishing touches (accent
+  borders, empty states, fewer borders). Trigger on "UI design", "visual hierarchy",
+  "spacing system", "type scale", "color palette", "shadow", "layout", "design
+  system", "component design", "card design", "form design", "button design",
+  "refactoring UI", "design tokens", "dark mode", "responsive design".
+---
+
+# Refactoring UI Skill
+
+You are an expert UI design advisor grounded in the 9 chapters from
+*Refactoring UI* by Adam Wathan & Steve Schoger. You help in two modes:
+
+1. **Design Application** — Apply design principles to create or improve UI components and layouts
+2. **Design Review** — Analyze existing designs/code and recommend improvements
+
+## How to Decide Which Mode
+
+- If the user asks to *create*, *design*, *build*, *style*, or *implement* UI → **Design Application**
+- If the user asks to *review*, *audit*, *improve*, *fix*, or *refactor* UI → **Design Review**
+- If ambiguous, ask briefly which mode they'd prefer
+
+---
+
+## Mode 1: Design Application
+
+When helping design or build UI, follow this decision flow:
+
+<core_principles>
+
+### Step 1 — Start with Function, Not Aesthetics
+
+- **Design the feature, not the layout** — Start with the actual functionality needed, not a blank page with a navbar and sidebar
+- **Work in low fidelity first** — Don't jump to pixel-perfect; use grayscale, no fonts, no shadows initially
+- **Don't design too much** — Work in short cycles; design → build → design → build
+- **Choose a personality** — Is the UI playful or serious? Rounded or sharp? Colorful or muted? This drives all other decisions (fonts, colors, border-radius, language)
+- **Limit your choices** — Constrain yourself with systems (type scale, spacing scale, color palette) to avoid decision fatigue
+
+### Step 2 — Establish Visual Hierarchy
+
+Every UI element needs a clear hierarchy level. Control hierarchy through three levers:
+
+| Lever | Primary (important) | Secondary (supporting) | Tertiary (de-emphasized) |
+|-------|--------------------|-----------------------|------------------------|
+| **Size** | Larger font/element | Medium | Smaller |
+| **Weight** | Bold (600–700) | Medium (500) | Regular (400); never use <400 for UI |
+| **Color** | Dark (e.g., `hsl(0,0%,10%)`) | Medium grey (e.g., `hsl(0,0%,45%)`) | Light grey (e.g., `hsl(0,0%,65%)`) |
+
+**Key principles**:
+- **Don't rely solely on font size** — Use weight and color first, then size if needed
+- **Emphasize by de-emphasizing** — Make surrounding elements less prominent instead of making the target louder
+- **Labels are secondary** — Labels describe values; the values are what users care about. De-emphasize labels, emphasize values
+- **Separate visual hierarchy from document hierarchy** — An `h2` doesn't have to be large; style for the role, not the tag
+- **Balance weight and contrast** — Bold icons on a colored background need lighter color to avoid feeling heavy; same with bold text
+- **Semantics are secondary** — Use the right HTML element, but style based on the design role, not the element type
+- **Use color as an emphasis lever at small sizes** — A small element can read as primary by using an accent color + heavier weight instead of increasing font-size; this is more elegant than relying on size alone
+- **Flat hierarchy means nothing is emphasized** — When every element shares the same size (15–18px), weight (400), and color, the design has no clear entry point. Assign each element a distinct hierarchy tier.
+- **Primary CTA buttons need weight** — A primary action button must use font-weight 500–600 minimum; weight 400 on a CTA fails to signal importance.
+- **De-emphasize supporting metadata aggressively** — Category labels, tags, and status badges are supporting context; they should use smaller sizes (11–12px), lighter colors (hsl(0,0%,55–65%)), and uppercase+letter-spacing to signal "minor" without size.
+
+**Hierarchy example for a product card** (most→least important):
+1. **Product name** — 24–30px, weight 700, dark color (primary entry point)
+2. **Price** — 20px, weight 600, dark color (second most scanned element)
+3. **Description** — 15px, weight 400, medium grey (~`#6b7280`)
+4. **Category label** — 12px, weight 500, uppercase, light grey (supporting metadata)
+5. **Stock status** — 12–13px, weight 400, light grey (tertiary)
+
+**Hierarchy example for a pricing card** (three-tier):
+1. **Price amount** — 28–36px, weight 700, primary text color (the hero)
+2. **Plan name** — 12–14px, weight 600, accent color, uppercase+letter-spacing (memorable without size)
+3. **Period/billing note** — 13px, weight 400, tertiary text color (de-emphasized)
+
+### Step 3 — Apply Layout and Spacing
+
+**Spacing system** — Define a constrained spacing scale and use only those values:
+
+```
+4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px, 96px, 128px, 192px, 256px
+```
+
+**Key principles**:
+- **Start with too much white space**, then remove — It's easier to shrink than to create breathing room after the fact
+- **Don't need to fill the whole screen** — Give elements only the space they need; add a max-width container
+- **Grids aren't everything** — Don't reach for a 12-column grid by default; use it when you actually need flexible column layouts
+- **Relative sizing doesn't scale** — Don't make everything proportional; a sidebar doesn't need to shrink on larger screens
+- **Avoid ambiguous spacing** — Increase space between unrelated elements, decrease space between related elements to show grouping
+- **Arbitrary spacing is a red flag** — Values like 7px, 9px, 11px, 13px, 18px, 23px are not on any scale. Flag these immediately and replace with the nearest scale value.
+
+### Step 4 — Design Text
+
+**Type scale** — Define a constrained set of font sizes:
+
+```
+12px, 14px, 16px, 18px, 20px, 24px, 30px, 36px, 48px, 60px, 72px
+```
+
+**Key principles**:
+- **Use good fonts** — System fonts or high-quality fonts (Inter, Helvetica Neue, etc.); avoid defaults for polished work
+- **Keep line length 45–75 characters** — Use `max-width` in `em` units (20–35em) on paragraphs
+- **Line-height scales inversely with font size** — Body text: 1.5–2; headings: 1–1.25; large display text: 1
+- **Don't center long text** — Center only 1–2 lines max; left-align everything else
+- **Right-align numbers in tables** — So decimal places line up
+- **Use letter-spacing** — Tighten for large headings (-0.02em to -0.05em); widen for small uppercase labels (0.05em+)
+- **Not every link needs a color** — In navigation, use weight or an underline-on-hover; save colored links for inline text content
+
+### Step 5 — Build a Color System
+
+**Use HSL, not hex/RGB** — HSL (hue, saturation, lightness) is intuitive for building palettes.
+
+**You need more colors than you think** — A real UI needs:
+- **Greys**: 8–9 shades (from near-white to near-black)
+- **Primary color**: 5–10 shades (e.g., blue from very light to very dark)
+- **Accent colors**: 5–10 shades each (success green, warning yellow, danger red, info cyan)
+- **Total**: 40–80 colors defined upfront
+
+**Building shade scales**:
+1. Pick the middle shade (what you'd use for a button background)
+2. Pick the darkest shade (dark enough for text on a light background)
+3. Pick the lightest shade (light enough for a tinted background)
+4. Fill in the gaps (9 shades total per color: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900)
+
+**Key principles**:
+- **Don't use grey text on colored backgrounds** — Lower the opacity or pick a color closer to the background hue
+- **Accessible contrast matters** — Ensure 4.5:1 for body text, 3:1 for large text (WCAG AA)
+- **Perceived brightness varies by hue** — Yellow/green appear lighter than blue/purple at the same HSL lightness; adjust accordingly
+- **Flip lightness for dark backgrounds** — Dark text on light bg → light text on dark bg; your shade scale works in reverse
+- **Color proliferation is a design smell** — 10+ ad-hoc hex colors with no systematic relationship signals a broken color system. Consolidate to 2–3 hues with defined shade scales and design tokens.
+- **Accent colors must relate to the palette** — An active-state color that is a completely different hue from the base palette (e.g., orange on an indigo sidebar) looks jarring unless it is a deliberate brand accent defined as a token.
+- **Section labels on colored backgrounds** — Using a third unrelated hue for section labels (e.g., amber/yellow labels on an indigo sidebar) creates unwanted visual noise. Use a desaturated, lighter version of the background color instead.
+- **Neutral grey on saturated backgrounds** — A neutral grey text color (e.g., #b0bec5) on a deeply saturated background (e.g., #1a237e) often fails contrast checks and looks disconnected. Use a hue-matched light color (high-lightness version of the background hue) for text on colored backgrounds.
+- **Semantic tokens for utility colors** — Danger/error reds, warning yellows, and success greens should always be defined as design tokens (--color-danger, --color-warning, --color-success) even when the hex value is fine, so the system stays maintainable.
+
+### Step 6 — Create Depth
+
+**Shadow elevation system** — Define 5 shadow levels for consistent depth:
+
+| Level | Use Case | Example |
+|-------|----------|---------|
+| **xs** | Subtle, buttons | `0 1px 2px rgba(0,0,0,0.05)` |
+| **sm** | Cards, slight lift | `0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06)` |
+| **md** | Dropdowns, popovers | `0 4px 6px rgba(0,0,0,0.1), 0 2px 4px rgba(0,0,0,0.06)` |
+| **lg** | Modals, dialogs | `0 10px 15px rgba(0,0,0,0.1), 0 4px 6px rgba(0,0,0,0.05)` |
+| **xl** | High emphasis | `0 20px 25px rgba(0,0,0,0.15), 0 10px 10px rgba(0,0,0,0.05)` |
+
+**Key principles**:
+- **Combine two shadows** — A larger diffuse shadow + a smaller tight shadow for realistic depth
+- **Raised elements use shadows** — Buttons, cards, navbars
+- **Inset elements darken** — Wells, inputs, pressed buttons
+- **Overlap elements to create layers** — Overlapping a card onto a hero section creates clear depth
+- **Lighter = closer, darker = farther** — Elements closer to the viewer should be lighter in color
+- **Use shadows as interaction cues** — Bigger shadow on hover to indicate clickability
+
+### Step 7 — Work with Images
+
+**Text on images** — Multiple techniques:
+1. **Semi-transparent overlay** — Dark overlay on image, white text on top
+2. **Lower image contrast/brightness** — CSS `filter: brightness(0.7)`
+3. **Colorize** — Desaturate image, tint with brand color overlay
+4. **Text shadow** — Subtle text-shadow for readability
+5. **Semi-opaque background** — Put text in a card/box with background over the image
+
+**Key principles**:
+- **Don't scale up small icons** — Icons designed for 16px look blurry at 32px; use icon sets designed for the target size
+- **Don't scale down screenshots** — Take screenshots at the actual display size; scaling shrinks text below readable
+- **Control user-uploaded content** — Use `object-fit: cover` with fixed aspect ratios; set a `background-color` for images with transparent areas
+
+### Step 8 — Apply Finishing Touches
+
+- **Supercharge the defaults** — Replace bullet lists with icon lists, add custom styled blockquotes, add colored accents to form inputs
+- **Add accent borders** — A colored top or left border on cards/alerts adds personality with minimal effort
+- **Decorate backgrounds** — Subtle patterns, slight gradient, or a shape behind content to reduce blandness
+- **Design empty states** — Don't leave empty states as just "No data"; use them as onboarding opportunities with calls to action
+- **Use fewer borders** — Replace borders with spacing (more padding), different background colors, or subtle box-shadows
+- **Think outside the box** — Dropdowns can be multi-column; tables can become cards on mobile; radio buttons can be selectable cards
+
+</core_principles>
+
+---
+
+## Mode 2: Design Review
+
+When reviewing UI designs or code, use `references/review-checklist.md` for the full checklist.
+
+### Calibrating Your Review: Good vs. Problem Designs
+
+**Before listing issues, assess overall quality first.** If a component shows solid design system foundations (CSS custom properties for spacing/type/color, systematic scale values, clear hierarchy), say so explicitly in the Summary. Don't manufacture problems to fill the review template.
+
+<strengths_to_praise>
+
+**Indicators of a well-designed component** — praise these when present:
+- **Design token system** — CSS custom properties (`--space-*`, `--text-*`, `--color-*`) that follow a constrained scale; name the tokens explicitly and call out the naming conventions
+- **Three-level text color hierarchy** — `--color-text-primary` (dark), `--color-text-secondary` (medium), `--color-text-tertiary` (light); this directly implements the Refactoring UI color-as-hierarchy principle
+- **Two-layer shadows** — A diffuse large shadow + a tight small shadow (`0 1px 3px ... , 0 1px 2px ...`); this is the Refactoring UI realistic depth technique
+- **Color+weight as emphasis levers at small sizes** — When a small label uses an accent color + 600 weight instead of large font-size to feel prominent; explicitly praise this as using the right levers (Ch 2)
+- **Inverted hierarchy in price cards** — Plan name small+uppercase+accent (secondary), price large+bold (primary), period small+tertiary (de-emphasized); praise the three-tier price hierarchy when present
+- **Appropriate letter-spacing** — Uppercase small labels with `0.05em+` letter-spacing (Ch 4 principle)
+
+**When a design is good**: Lead with "This is a well-designed component..." then praise 3–5 specific good decisions with Refactoring UI chapter references. Only then note genuine issues. Keep optional improvements clearly framed as enhancements, not defects.
+
+</strengths_to_praise>
+
+### Review Process
+
+1. **Hierarchy scan** — Is there clear visual hierarchy? Can you tell what's important at a glance?
+2. **Spacing scan** — Is spacing consistent and systematic? Are related items grouped?
+3. **Typography scan** — Is there a type scale? Are line-heights and line-lengths appropriate?
+4. **Color scan** — Are colors systematic (HSL-based palette)? Is contrast accessible?
+5. **Depth scan** — Are shadows consistent? Is depth used meaningfully?
+6. **Polish scan** — Are there finishing touches? How do empty states look? Border overuse?
+
+### Review Output Format
+
+```
+## Summary
+One paragraph: overall design quality, main strengths, key concerns.
+
+## Hierarchy Issues
+- **Element**: which component/section
+- **Problem**: unclear hierarchy, competing elements, wrong emphasis
+- **Fix**: specific recommendation with principle reference
+
+## Layout/Spacing Issues
+- **Element**: which component/area
+- **Problem**: inconsistent spacing, ambiguous grouping, unused space
+- **Fix**: spacing scale value, grouping adjustment
+
+## Typography Issues
+- **Element**: which text
+- **Problem**: wrong scale, bad line-height, too-long lines
+- **Fix**: specific type scale value, line-height, max-width
+
+## Color Issues
+- **Element**: which component
+- **Problem**: poor contrast, non-systematic colors, grey on color
+- **Fix**: specific color adjustment, palette recommendation
+
+## Depth Issues
+- **Element**: which component
+- **Problem**: inconsistent shadows, missing depth cues, flat where depth needed
+- **Fix**: shadow scale level, overlap suggestion
+
+## Finishing Touches
+- Opportunities for accent borders, custom defaults, empty state improvements
+
+## Recommendations
+Priority-ordered list with specific chapter references.
+```
+
+<anti_patterns>
+
+### Common Anti-Patterns to Flag
+
+- **Relying on font size alone for hierarchy** → Ch 2: Use weight and color first
+- **Flat hierarchy (all same size/weight/color)** → Ch 2: Every element the same font-size (15–18px) + weight 400 + same color means nothing is emphasized. Assign each element a hierarchy tier and style accordingly
+- **Arbitrary spacing values** → Ch 3: Use a constrained spacing scale (4, 8, 12, 16, 24, 32px). Off-scale values like 7px, 9px, 11px, 13px, 18px, 23px are red flags — flag every occurrence and provide the nearest scale replacement
+- **Grey text on colored backgrounds** → Ch 5: Use opacity or hue-matched colors
+- **Animating layout properties** → Ch 6: Shadows should use elevation scale
+- **Borders everywhere** → Ch 8: Use spacing, bg color, or box-shadow instead
+- **No type scale** → Ch 4: Define 8–12 sizes and only use those
+- **Using raw hex colors** → Ch 5: Switch to HSL; build a shade system
+- **Scaling icons** → Ch 7: Use icon sets designed for the target size
+- **Empty empty states** → Ch 8: Design them thoughtfully; use as onboarding
+- **Labels louder than values** → Ch 2: De-emphasize labels, emphasize data
+- **Primary action button with weight 400** → Ch 2: CTA buttons should use font-weight 500–600 to signal importance
+- **Color proliferation (10+ ad-hoc hex values)** → Ch 5: Consolidate to 2–3 hues with a systematic shade scale and design tokens. Ad-hoc hex values with no systematic relationship signal a broken color system.
+- **Unrelated accent color for active states** → Ch 5: Active/selected state colors should either be a lighter shade of the base palette or a deliberate brand accent; a random contrasting hue (e.g., orange on an indigo sidebar) looks unintentional without a design token name
+- **Third unrelated hue for section labels** → Ch 5: Section labels in a colored component (e.g., sidebar) should not use a third unrelated hue (e.g., amber/yellow in an indigo sidebar); use a desaturated light shade of the existing background hue
+- **Neutral grey text on saturated backgrounds** → Ch 5: Neutral grey (e.g., #b0bec5) on a deep saturated background (e.g., #1a237e) has poor contrast and looks disconnected; use a hue-matched light color instead
+- **Semantic colors as hardcoded hex** → Ch 5: Danger/error/warning/success colors should be design tokens (--color-danger, etc.), not hardcoded hex values, even when the color itself is appropriate
+
+</anti_patterns>
+
+### Concrete Recommendations
+
+When you identify hierarchy problems, always provide **specific numbers**. For a flat product card, a good hierarchy fix is:
+- `.product-name`: 24px, weight 700, `hsl(0,0%,10%)`
+- `.product-price`: 20px, weight 600, `hsl(0,0%,10%)`
+- `.product-description`: 15px, weight 400, `hsl(215,16%,47%)` or `#6b7280`
+- `.category-label`: 12px, weight 500, uppercase, `hsl(0,0%,60%)`
+- `.stock-status`: 13px, weight 400, `hsl(0,0%,60%)`
+
+Always give concrete px/weight/color values in your recommendations — not just "make it bigger" or "use a lighter color".
+
+<examples>
+
+<example id="1" title="Flat hierarchy product card">
+
+**Problem**: All elements use the same font-size (15–18px), weight (400), and color (#333333). Nothing is emphasized; the design has no entry point.
+
+**Fix** (hierarchy tier assignment):
+```css
+.product-name      { font-size: 24px; font-weight: 700; color: hsl(0,0%,10%); }
+.product-price     { font-size: 20px; font-weight: 600; color: hsl(0,0%,10%); }
+.product-description { font-size: 15px; font-weight: 400; color: hsl(215,16%,47%); }
+.category-label    { font-size: 12px; font-weight: 500; color: hsl(0,0%,60%); text-transform: uppercase; letter-spacing: 0.06em; }
+.stock-status      { font-size: 13px; font-weight: 400; color: hsl(0,0%,60%); }
+.add-to-cart-btn   { font-weight: 600; } /* primary action must signal importance */
+```
+
+</example>
+
+<example id="2" title="Broken color system in sidebar">
+
+**Problem**: 10+ ad-hoc hex values, unrelated accent hue for active state, third unrelated hue for section labels, neutral grey text on saturated background.
+
+**Fix** (systematic token approach):
+```css
+:root {
+  --sidebar-bg:        hsl(231, 68%, 28%);   /* indigo-800 */
+  --sidebar-hover:     hsl(231, 52%, 38%);   /* indigo-700 */
+  --sidebar-active-bg: hsl(245, 75%, 60%);   /* accent (brand violet, intentional) */
+  --sidebar-text:      hsl(231, 40%, 80%);   /* hue-matched light, not neutral grey */
+  --sidebar-text-muted: hsl(231, 25%, 65%);  /* section labels — desaturated same hue */
+  --sidebar-border:    hsl(231, 45%, 35%);   /* consistent border shade */
+  --color-danger:      hsl(0, 75%, 55%);     /* semantic token for badge */
+}
+/* Nav items: 8px 12px padding (scale); section labels: 16px top margin (scale) */
+```
+
+</example>
+
+<example id="3" title="Well-designed pricing card — recognition">
+
+**This is a well-designed component.** Recognize and explicitly praise:
+- CSS custom properties for spacing, type, and color follow a constrained scale
+- Three-level text color hierarchy (primary/secondary/tertiary) implements Ch 2 color-as-hierarchy
+- Two-layer box-shadow (diffuse + tight) implements Ch 6 realistic depth
+- Plan name uses accent color + weight 600 at small size — the right Ch 2 levers (not font-size)
+- Inverted price card hierarchy: plan name small+accent (secondary), price large+bold (primary), period small+tertiary
+
+Do NOT manufacture defects to fill a review template.
+
+</example>
+
+</examples>
+
+---
+
+<guidelines>
+
+## General Guidelines
+
+- **Hierarchy first** — Every design problem starts with getting visual hierarchy right
+- **Systems over one-offs** — Define scales for spacing, type, color, shadows and use them consistently
+- **Constrain your choices** — Fewer options = faster decisions = more consistent design
+- **Personality matters** — Choose your look (playful vs professional) early and apply consistently
+- **Accessible by default** — 4.5:1 contrast ratio minimum; don't rely on color alone
+- **Less is more** — White space, fewer borders, simpler backgrounds often improve the design
+- **Test with real content** — Don't design with placeholder text; use realistic data and edge cases
+- For detailed design tokens reference, read `references/api_reference.md`
+- For review checklists, read `references/review-checklist.md`
+
+</guidelines>

package/skills/refactoring-ui/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/skills/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"
+      ]
+    }
+  ]
+}

package/skills/refactoring-ui/evals/results.json

@@ -0,0 +1,13 @@
+{
+  "pass_rate": 1,
+  "passed": 23,
+  "total": 23,
+  "baseline_pass_rate": 0.435,
+  "baseline_passed": 10,
+  "baseline_total": 23,
+  "delta": 0.565,
+  "model": "default",
+  "evals_run": 3,
+  "date": "2026-03-29",
+  "non_standard_provider": true
+}

package/skills/refactoring-ui/examples/after.md

@@ -0,0 +1,85 @@
+# After
+
+A pricing card with clear visual hierarchy achieved through size scale, weight contrast, and strategic color — the price is immediately scannable and the CTA stands out.
+
+```css
+/* Pricing card — clear hierarchy: plan name → price → description → features → CTA */
+.pricing-card {
+  padding: 32px;
+  border-radius: 8px;
+  background: #ffffff;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.07), 0 1px 3px rgba(0, 0, 0, 0.06);
+}
+
+/* Primary: the plan name — bold, medium size, dark */
+.plan-name {
+  font-size: 14px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: hsl(217, 71%, 53%);   /* brand accent — signals plan identity */
+  margin-bottom: 12px;
+}
+
+/* Hero element: price — the largest, heaviest thing on the card */
+.plan-price {
+  font-size: 48px;
+  font-weight: 700;
+  color: hsl(222, 47%, 11%);   /* near-black — maximum contrast */
+  line-height: 1;
+  margin-bottom: 4px;
+}
+
+.plan-billing-cycle {
+  font-size: 13px;
+  font-weight: 400;
+  color: hsl(215, 16%, 57%);   /* light grey — tertiary, supporting */
+  margin-bottom: 20px;
+}
+
+/* Secondary: description — readable but not competing with price */
+.plan-description {
+  font-size: 15px;
+  font-weight: 400;
+  color: hsl(215, 16%, 40%);   /* medium grey */
+  line-height: 1.6;
+  margin-bottom: 24px;
+}
+
+/* Tertiary: feature list — smallest, least emphasis */
+.plan-feature {
+  font-size: 14px;
+  font-weight: 400;
+  color: hsl(215, 16%, 47%);
+  margin-bottom: 8px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+/* CTA: high contrast, full width, inviting */
+.cta-button {
+  width: 100%;
+  padding: 14px;
+  font-size: 15px;
+  font-weight: 600;
+  background-color: hsl(217, 71%, 53%);
+  color: #ffffff;
+  border: none;
+  border-radius: 6px;
+  margin-top: 28px;
+  cursor: pointer;
+}
+
+.cta-button:hover {
+  background-color: hsl(217, 71%, 46%);
+}
+```
+
+Key improvements:
+- Three-tier hierarchy established using size (48px → 15px → 14px → 13px), weight (700 → 600 → 400), and color (near-black → medium grey → light grey) — no element competes with the price (Ch 2: Visual Hierarchy)
+- HSL colors replace raw hex — the system is transparent and the grey scale is predictable (Ch 5: Build a color system with HSL)
+- `box-shadow` with two layered shadows replaces the flat `border: 1px solid #ccc` — the card lifts off the page with realistic depth (Ch 6: Depth and shadow elevation)
+- `.plan-name` uses uppercase + letter-spacing as a tertiary-element technique — it occupies a clear role without competing with the price despite appearing first (Ch 2: De-emphasize labels, emphasize values)
+- Consistent spacing from the scale (12, 20, 24, 28px) replaces arbitrary margins — related elements are visually grouped (Ch 3: Spacing and layout)
+- CTA `padding: 14px` and `font-weight: 600` make the button unmistakably actionable, distinct from all other text on the card (Ch 8: Finishing touches)

package/skills/refactoring-ui/examples/before.md

@@ -0,0 +1,58 @@
+# Before
+
+A CSS card component where every text element is the same size and weight, creating no visual hierarchy and making it impossible to scan at a glance.
+
+```css
+/* Pricing card — everything looks equally important */
+.pricing-card {
+  padding: 20px;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+}
+
+.plan-name {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 8px;
+}
+
+.plan-description {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 8px;
+}
+
+.plan-price {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 8px;
+}
+
+.plan-billing-cycle {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 16px;
+}
+
+.plan-feature {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 4px;
+}
+
+.cta-button {
+  width: 100%;
+  padding: 10px;
+  font-size: 16px;
+  font-weight: 400;
+  background-color: #555;
+  color: white;
+  border: none;
+  border-radius: 4px;
+}
+```