@booklib/skills 1.0.0

package/refactoring-ui/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: refactoring-ui
+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:
+
+### 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
+
+### 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
+
+### 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
+
+### 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
+
+---
+
+## Mode 2: Design Review
+
+When reviewing UI designs or code, use `references/review-checklist.md` for the full checklist.
+
+### 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.
+```
+
+### Common Anti-Patterns to Flag
+
+- **Relying on font size alone for hierarchy** → Ch 2: Use weight and color first
+- **Arbitrary spacing values** → Ch 3: Use a constrained spacing scale
+- **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
+
+---
+
+## 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`

package/refactoring-ui/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/refactoring-ui/references/api_reference.md

@@ -0,0 +1,355 @@
+# Refactoring UI — Design Tokens & Systems Reference
+
+Complete catalog of design systems, scales, and token values from all 9 chapters.
+
+---
+
+## Ch 1: Starting from Scratch
+
+### Design Process
+- Start with a feature, not a layout — don't begin with shell (navbar, sidebar, footer)
+- Work low-fidelity first: grayscale, no shadows, system fonts, constrained sizes
+- Design in cycles: design a simple version → build it → iterate on the real thing
+- Hold the detail — don't waste time on perfect icons or color when the layout isn't right
+- Don't over-design: only design the next thing you're going to build
+
+### Choosing a Personality
+Personality should be decided before picking any specific design values:
+
+| Attribute | Elegant/Formal | Neutral/Safe | Playful/Fun |
+|-----------|---------------|-------------|-------------|
+| **Font** | Serif, thin sans-serif | System fonts, clean sans | Rounded sans, display fonts |
+| **Color** | Muted, few hues, gold/navy | Blue, grey, safe palette | Bright, saturated, many hues |
+| **Border-radius** | None or minimal (0–2px) | Small (4px) | Large (8px–full) |
+| **Language** | Formal, professional | Neutral, clear | Casual, friendly, fun |
+
+### Limiting Your Choices
+- **Define systems in advance**: type scale, spacing scale, color palette, shadow scale, font weights, border-radius, width, opacity
+- **Design by choosing from constrained options**, not by picking arbitrary values
+- Systems provide speed (fewer decisions) and consistency (same values everywhere)
+
+---
+
+## Ch 2: Hierarchy is Everything
+
+### The Three Levers of Hierarchy
+1. **Size** — Larger = more important
+2. **Weight** — Bolder = more important (use 600–700 for emphasis, 400–500 for normal; never go below 400 for UI text)
+3. **Color** — Darker = more important
+
+### Text Color System (Light Background)
+| Role | Description | Example Value |
+|------|-------------|---------------|
+| **Primary** | Main content, headings, important text | `hsl(0, 0%, 10%)` — near-black |
+| **Secondary** | Supporting text, descriptions, meta | `hsl(0, 0%, 45%)` — medium grey |
+| **Tertiary** | Placeholders, disabled, timestamps | `hsl(0, 0%, 65%)` — light grey |
+
+### Emphasis Techniques
+- **Don't just make things bigger** — Try weight and color changes first
+- **Emphasize by de-emphasizing surroundings** — Make competing elements less prominent
+- **Labels as supporting cast** — Labels describe data; the data itself should be emphasized
+- **Visual hierarchy ≠ document hierarchy** — An `<h1>` can be small if it's not the focal point
+- **Bold icons need softer color** — Heavy visual weight + high contrast = too loud
+
+### Icon Sizing in Context
+- Icons next to text: match the font size or slightly smaller
+- Icons as primary elements: can be larger, but tone down color/weight to balance
+- Avoid scaling icons beyond their designed size — use different icon sets for different sizes
+
+---
+
+## Ch 3: Layout and Spacing
+
+### Spacing Scale
+A limited set of spacing values to use everywhere:
+
+```
+4px   — Tight: icon-to-label gap, inline element spacing
+8px   — Compact: tight form fields, dense lists
+12px  — Default small: label-to-input, list item padding
+16px  — Default: standard padding, gaps between small elements
+24px  — Comfortable: card padding, section gaps within a component
+32px  — Roomy: between components in a group
+48px  — Spacious: between distinct sections
+64px  — Section: major section separators
+96px  — Large: between page sections
+128px — Extra large: hero/header padding
+192px — Maximum padding for very large screens
+256px — Full-width section padding on desktops
+```
+
+### Layout Principles
+- **Start with too much white space, then remove** — Easier to tighten than to create breathing room
+- **Don't fill the screen** — Use max-width (e.g., 600–800px for content, 1200px for full layouts)
+- **Grids are a tool, not a rule** — Use them when you need proportional columns; many layouts don't need a grid
+- **Relative sizing doesn't scale** — A 250px sidebar is fine at all widths; don't make it 20% of viewport
+- **Dense UIs need smaller spacing** — Dashboards and data-heavy UIs can use tighter spacing from the scale
+- **Generous UIs need larger spacing** — Marketing pages and hero sections use wider spacing
+
+### Grouping with Spacing
+- **Close = related** — Elements that belong together should have less space between them
+- **Far = unrelated** — Use larger spacing to separate distinct groups
+- **Ambiguous spacing is the enemy** — If spacing between items is uniform, the grouping is unclear
+
+---
+
+## Ch 4: Designing Text
+
+### Type Scale
+A limited set of font sizes to use everywhere:
+
+```
+12px — Fine print, captions, badges
+14px — Secondary text, meta information, labels
+16px — Body text (base size for most interfaces)
+18px — Slightly emphasized body, lead paragraphs
+20px — Large body, small headings, subheadings
+24px — Section headings (h3 equivalent)
+30px — Page section headings (h2 equivalent)
+36px — Page titles, hero subheadings
+48px — Display headings, hero titles
+60px — Large display, landing page headlines
+72px — Extra-large display, maximum emphasis
+```
+
+### Font Weight Scale
+| Weight | Use |
+|--------|-----|
+| 400 (Regular) | Body text, descriptions, de-emphasized content |
+| 500 (Medium) | Slightly emphasized body, labels, navigation |
+| 600 (Semi-bold) | Headings, buttons, emphasized text |
+| 700 (Bold) | Strong emphasis, primary headings |
+
+**Never use weights below 400** for UI text — they're too hard to read.
+
+### Line-Height Guidelines
+| Font Size | Recommended Line-Height |
+|-----------|------------------------|
+| 12–14px | 1.5–1.75 (more leading for small text) |
+| 16–18px | 1.5 (standard reading comfort) |
+| 20–24px | 1.25–1.4 (can tighten slightly) |
+| 30–48px | 1.1–1.25 (headings need less) |
+| 48px+ | 1–1.1 (display text: nearly solid) |
+
+### Line Length
+- **Optimal**: 45–75 characters per line
+- **Implementation**: `max-width: 20em` to `35em` on text containers
+- **Centered text**: Only for 1–2 lines maximum; left-align everything else
+
+### Letter-Spacing
+| Context | Letter-Spacing |
+|---------|---------------|
+| Large headings (36px+) | -0.02em to -0.05em (tighten) |
+| Normal body text | 0 (default) |
+| Small uppercase labels | +0.05em to +0.1em (widen) |
+| All-caps text | +0.05em (widen for readability) |
+
+### Link Styling
+- **In body text**: Colored + underlined (or underlined on hover)
+- **In navigation**: No special color; use weight, underline-on-hover, or active indicator
+- **In cards**: The whole card can be clickable; no link styling needed
+
+---
+
+## Ch 5: Working with Color
+
+### HSL Color Model
+```
+hsl(hue, saturation%, lightness%)
+```
+- **Hue**: 0–360 (color wheel: 0=red, 120=green, 240=blue)
+- **Saturation**: 0%=grey, 100%=vivid
+- **Lightness**: 0%=black, 50%=pure color, 100%=white
+
+### Building a Complete Palette
+
+**Greys (8–9 shades)**:
+| Shade | Lightness Range | Use |
+|-------|----------------|-----|
+| 50 | 97–98% | Page backgrounds, subtle tints |
+| 100 | 93–95% | Card backgrounds, alternate rows |
+| 200 | 85–90% | Borders, dividers |
+| 300 | 75–80% | Disabled text, placeholder icons |
+| 400 | 60–65% | Placeholder text |
+| 500 | 45–50% | Secondary text |
+| 600 | 35–40% | Icons, labels |
+| 700 | 25–30% | Secondary headings |
+| 800 | 15–20% | Primary text, headings |
+| 900 | 5–10% | Maximum emphasis text |
+
+**Primary/Accent colors (5–10 shades each)**:
+Follow same pattern: pick middle (button bg), darkest (text), lightest (tinted bg), fill in between.
+
+### Color Accessibility
+| Standard | Ratio | When |
+|----------|-------|------|
+| WCAG AA (normal text) | 4.5:1 | Body text, labels, inputs |
+| WCAG AA (large text) | 3:1 | Headings 18px+ bold, or 24px+ |
+| WCAG AAA (normal) | 7:1 | Enhanced accessibility |
+
+### Grey on Colored Backgrounds
+**Problem**: Pure grey (`hsl(0, 0%, X%)`) looks washed out on colored backgrounds.
+
+**Solutions**:
+1. **Reduce opacity**: `rgba(255,255,255,0.8)` on dark bg; `rgba(0,0,0,0.5)` on light bg
+2. **Hand-pick**: Choose a color with same hue as background but adjusted saturation/lightness
+
+### Perceived Brightness by Hue
+Hues have different apparent brightness at same HSL lightness:
+- **Brightest** (feel lighter): Yellow (60°), Cyan (180°), Green (120°)
+- **Darkest** (feel darker): Blue (240°), Red (0°), Magenta (300°)
+- Adjust lightness values to compensate when building palettes across hues
+
+### Dark Mode Adaptation
+- Reverse the shade scale: shade-900 becomes background, shade-50 becomes text
+- Reduce saturation slightly (vivid colors are harsh on dark backgrounds)
+- Shadows are less visible on dark — use subtle glows or border accents instead
+- Test carefully: contrast requirements still apply
+
+---
+
+## Ch 6: Creating Depth
+
+### Shadow Elevation Scale
+
+```css
+--shadow-xs:  0 1px 2px rgba(0,0,0,0.05);
+--shadow-sm:  0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06);
+--shadow-md:  0 4px 6px rgba(0,0,0,0.1), 0 2px 4px rgba(0,0,0,0.06);
+--shadow-lg:  0 10px 15px rgba(0,0,0,0.1), 0 4px 6px rgba(0,0,0,0.05);
+--shadow-xl:  0 20px 25px rgba(0,0,0,0.15), 0 10px 10px rgba(0,0,0,0.05);
+```
+
+### Shadow Best Practices
+- **Two shadows per level**: Large diffuse + small tight for realism
+- **Raised elements**: Buttons, cards, navbars, floating action buttons
+- **Inset elements**: Input fields, wells, pressed button states
+- **Interactive shadows**: Increase shadow on hover (sm → md) to show clickability
+- **Don't overdo flat design**: Some depth helps users understand interactive affordances
+- **Keep it consistent**: Use only the defined scale; no random shadow values
+
+### Depth Through Overlap
+- Offset an element (e.g., card) so it overlaps a background section
+- Creates visual layering without shadows
+- Negative margins or absolute positioning to achieve the overlap
+
+### Color and Depth
+- **Lighter elements appear closer** to the viewer
+- **Darker elements appear farther** away
+- Use this with shadows: elevated elements can also be slightly lighter in bg color
+
+---
+
+## Ch 7: Working with Images
+
+### Text on Images
+
+| Technique | CSS | Best For |
+|-----------|-----|----------|
+| Dark overlay | `background: linear-gradient(rgba(0,0,0,0.5), rgba(0,0,0,0.5)), url(...)` | Hero sections |
+| Lower brightness | `filter: brightness(0.7)` | Subtle dimming |
+| Colorize | `filter: grayscale(100%); mix-blend-mode: multiply` + color overlay | Brand consistency |
+| Text shadow | `text-shadow: 0 2px 4px rgba(0,0,0,0.5)` | Quick fix |
+| Scrim/card | Semi-opaque `background-color` on text container | Readable blocks |
+
+### Image Sizing
+
+| Scenario | Approach |
+|----------|----------|
+| Icons at different sizes | Use different icon sets (16px, 24px, 32px) — don't scale |
+| Screenshots in marketing | Capture at display size; don't scale down |
+| User-uploaded avatars | `object-fit: cover` + fixed aspect ratio + bg color fallback |
+| User-uploaded hero images | `object-fit: cover` + fixed height + handle extremes (panoramic, portrait) |
+
+### Object-Fit Values
+```css
+object-fit: cover;   /* Crop to fill — best for avatars, hero images */
+object-fit: contain;  /* Fit inside — best for product images, logos */
+object-fit: fill;     /* Stretch — avoid for most UI use cases */
+```
+
+---
+
+## Ch 8: Finishing Touches
+
+### Accent Borders
+```css
+/* Top accent on card */
+.card { border-top: 4px solid var(--primary-500); }
+
+/* Left accent on alert */
+.alert { border-left: 4px solid var(--warning-500); }
+
+/* Color-code by type */
+.alert-success { border-left-color: var(--success-500); }
+.alert-danger  { border-left-color: var(--danger-500); }
+```
+
+### Replacing Borders
+| Instead of Border | Try |
+|-------------------|-----|
+| Between list items | More padding/spacing between items |
+| Around cards | Box-shadow (subtle shadow creates implied boundary) |
+| Between sections | Different background color |
+| Around inputs | Background color difference + subtle shadow |
+
+### Empty States
+- **Don't**: Show just "No items found" in grey text
+- **Do**: Show an illustration + explanation + primary call to action
+- **Example**: "No projects yet — Create your first project" with a big button
+- Empty states are onboarding opportunities
+
+### Custom Defaults
+| Default Element | Upgrade |
+|----------------|---------|
+| Bullet lists | Icon lists (checkmarks, arrows, custom icons) |
+| Blockquotes | Large border-left + background tint + italic |
+| Form inputs | Colored focus ring, custom checkbox/radio |
+| Tables | Alternating rows, sticky headers, row hover |
+| Links | Custom underline color/thickness |
+
+---
+
+## Ch 9: Leveling Up
+
+### Learning Approach
+- **Steal from good designs** — Rebuild UIs you admire to understand why they work
+- **Analyze decisions** — Ask "why does this work?" not just "what does it look like?"
+- **Think in systems** — Every decision should fit into a reusable system
+- **Look outside your domain** — SaaS, e-commerce, media, dashboards — all have lessons
+- **Rebuild for practice** — Pick a well-designed app and recreate a page pixel-by-pixel
+
+### Design System Assembly
+Collect all your scales into one system:
+
+```css
+:root {
+  /* Spacing */
+  --space-1: 4px;   --space-2: 8px;   --space-3: 12px;
+  --space-4: 16px;  --space-5: 24px;  --space-6: 32px;
+  --space-8: 48px;  --space-10: 64px; --space-12: 96px;
+  --space-16: 128px;
+
+  /* Type */
+  --text-xs: 12px;  --text-sm: 14px;  --text-base: 16px;
+  --text-lg: 18px;  --text-xl: 20px;  --text-2xl: 24px;
+  --text-3xl: 30px; --text-4xl: 36px; --text-5xl: 48px;
+
+  /* Font Weight */
+  --font-normal: 400; --font-medium: 500;
+  --font-semibold: 600; --font-bold: 700;
+
+  /* Shadows */
+  --shadow-xs: 0 1px 2px rgba(0,0,0,0.05);
+  --shadow-sm: 0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06);
+  --shadow-md: 0 4px 6px rgba(0,0,0,0.1), 0 2px 4px rgba(0,0,0,0.06);
+  --shadow-lg: 0 10px 15px rgba(0,0,0,0.1), 0 4px 6px rgba(0,0,0,0.05);
+  --shadow-xl: 0 20px 25px rgba(0,0,0,0.15), 0 10px 10px rgba(0,0,0,0.05);
+
+  /* Border Radius */
+  --radius-sm: 2px; --radius-md: 4px;
+  --radius-lg: 8px; --radius-full: 9999px;
+
+  /* Colors: define full shade scales for grey, primary, accent, etc. */
+}
+```