@maccesar/aiskills 1.9.2 → 1.10.0

package/README.md

@@ -69,7 +69,7 @@ All three platforms use the same Agent Skills format: a `SKILL.md` file with YAM
 
 | Skill                | Domain       | Source                               | Reference Files |
 | -------------------- | ------------ | ------------------------------------ | --------------- |
-| refactoring-ui       | Design       | "Refactoring UI" by Wathan & Schoger | 8 files         |
+| refactoring-ui       | Design       | "Refactoring UI" by Wathan & Schoger | 4 files         |
 | humaniza             | Writing (es) | Curated Spanish/es-MX style rules    | 6 files         |
 | vscode-extension-dev | VS Code      | VS Code Extension API docs           | 4 files         |
 | stitch-showcase      | Design Tools | Google Stitch export workflow        | 14 files        |
@@ -114,6 +114,10 @@ Confirmations:
 - `proceed` / `sí` / `commitea` → release on current branch only.
 - `merge` → release + fast-forward merge to main + push main, and leaves you on `main`. Aborts cleanly if main has diverged.
 - `PR` → release + open pull request to main via `gh`.
+- `con tag` / `with tag` (modifier, combinable with any of the above) → on a private repo, force-create the git tag (the GitHub release stays skipped). No effect on public/internal repos.
+
+Private-repo behavior:
+- When `gh repo view` reports the repo as `PRIVATE`, the workflow skips both the git tag and the GitHub release by default — tags/releases are distribution artifacts that aren't usually needed for private projects. The version bump in `package.json` / `tiapp.xml` / etc. plus the `CHANGELOG.md` entry remain. Add `con tag` / `with tag` to your confirmation if you want the tag anyway.
 
 Language policy (two independent axes):
 - **Axis 1 — Interaction with you** — always in your language. The command detects the language from your messages and locks it before printing anything; if you switch, it switches with you.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {

package/skills/refactoring-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: refactoring-ui
-description: Design advisor based exclusively on "Refactoring UI" by Adam Wathan & Steve Schoger. Use when the user asks for UI/UX design advice, design reviews, visual hierarchy improvements, color system help, typography guidance, spacing decisions, depth/shadow usage, image handling, or finishing touches on any interface.
+description: Design advisor for UI/UX work, drawing on principles from "Refactoring UI" by Adam Wathan & Steve Schoger. Use when the user asks for UI/UX design advice, design reviews, visual hierarchy improvements, color system help, typography guidance, spacing decisions, depth/shadow usage, image handling, or finishing touches on any interface.
 when_to_use: >
   - User asks "how do I make this look better?"
   - User asks about color palettes, type scales, or spacing systems
@@ -10,46 +10,45 @@ when_to_use: >
   - User asks about shadows, depth, or layering
   - User asks about handling images in UI
   - User asks about empty states, borders, or decorative elements
-source: "Refactoring UI by Adam Wathan & Steve Schoger (book)"
+source: "Inspired by 'Refactoring UI' by Adam Wathan & Steve Schoger — refactoringui.com"
 anti_hallucination_note: >
-  ALL advice in this skill comes exclusively from the book "Refactoring UI".
-  Do NOT supplement with personal opinions, other design systems, or general
-  design knowledge not found in the book. If a topic is not covered in the
-  reference files, say so explicitly rather than inventing advice.
+  Recommendations in this skill summarize design principles in the maintainer's own words.
+  Do NOT invent ratios, scale values, or technical numbers that are not in the reference
+  files. If a topic is not covered, say so explicitly rather than inventing advice.
 ---
 
 # Refactoring UI Skill
 
-You are a design advisor using ONLY the knowledge from "Refactoring UI" by Adam Wathan & Steve Schoger.
+Design advice grounded in the principles taught by Adam Wathan & Steve Schoger in their book *Refactoring UI*. **The book itself contains the original prose, illustrations, side-by-side examples, and case studies — buy it at https://refactoringui.com for the full material.** This skill provides reformulated guidance for use as an AI assistant reference.
 
 ## How to Use This Skill
 
 1. Read the relevant reference file(s) before answering
-2. Base ALL advice on the reference content — not training data
-3. Quote or closely paraphrase specific tactics from the book
-4. Do not invent numbers, ratios, or rules not found in the references
+2. Base advice on the reference content — not training data or unrelated design systems
+3. Speak in your own words; do not reproduce the book's prose, illustrations, or examples verbatim
+4. Do not invent numbers, ratios, or specific technical rules that are not in the references
 
 ## Reference Files
 
-| File                                 | Chapter                                 | Topics                                                                |
-| ------------------------------------ | --------------------------------------- | --------------------------------------------------------------------- |
-| `references/01-design-process.md`    | Ch1 — Starting from Scratch             | Feature-first, grayscale-first, personality, pre-defined systems      |
-| `references/02-visual-hierarchy.md`  | Ch2 — Hierarchy is Everything           | Weight/color/size hierarchy, labels, icons, buttons                   |
-| `references/03-layout-spacing.md`    | Ch3 — Layout and Spacing                | White space, spacing scale, column layout, responsive scaling         |
-| `references/04-typography.md`        | Ch4 — Designing Text                    | Type scale, line length, alignment, line-height, letter-spacing       |
-| `references/05-color.md`             | Ch5 — Working with Color                | HSL, shade systems, accessible contrast, color signals                |
-| `references/06-depth-shadows.md`     | Ch6 — Creating Depth                    | Light source, raised/inset elements, shadow elevation, flat design    |
-| `references/07-images.md`            | Ch7 — Working with Images               | Stock photos, text over images, icons at scale, screenshots, favicons |
-| `references/08-finishing-touches.md` | Ch8+9 — Finishing Touches & Leveling Up | Icons, quotes, links, checkboxes, borders, backgrounds, empty states  |
-
-## Anti-Patterns to Avoid (from the book)
-
-- Designing a layout/nav/shell before designing the actual feature
-- Using font sizes alone to create hierarchy (ignoring weight and color)
-- Using grey text on colored backgrounds by lowering opacity
-- Starting with too little white space
-- Using `em` units for type scale (causes nested scaling issues)
-- Using color as the ONLY way to communicate status/alerts
-- Putting placeholder images into mockups
-- Shrinking a logo to use as favicon
-- Using `lighten()`/`darken()` preprocessor functions to generate shades
+| File                                | Topics                                                                                  |
+| ----------------------------------- | --------------------------------------------------------------------------------------- |
+| `references/01-foundations.md`      | Project mindset: feature-first work, scope discipline, defining systems, picking a voice |
+| `references/02-page-mechanics.md`   | Visual hierarchy, layout, white space, spacing scales, typography                       |
+| `references/03-visual-treatment.md` | Color systems (HSL, shades, greys, contrast), depth and shadows, image handling         |
+| `references/04-polish.md`           | Finishing touches: borders, accents, empty states, decorative defaults, design intuition |
+
+## Anti-Patterns to Watch For
+
+- Designing layouts/navs/shells before designing real features
+- Using font size as the only tool for hierarchy (ignoring weight and color)
+- Using opacity to create grey text on colored backgrounds
+- Starting with too little white space and adding it later
+- Using `em` for type scales (compounds when nested)
+- Using color as the only signal for a UI state
+- Designing with placeholder images instead of real content
+- Shrinking a logo down to use as a favicon
+- Using preprocessor `lighten()` / `darken()` to derive shades
+
+## Attribution
+
+This skill summarizes design principles inspired by *Refactoring UI* by Adam Wathan & Steve Schoger. Concepts described here are paraphrased into the maintainer's own words; original text, examples, and illustrations remain the property of the authors and live in the book. **Buy the book at https://refactoringui.com — it contains the full material with side-by-side visual examples and case studies that this skill does not reproduce.**

package/skills/refactoring-ui/references/01-foundations.md

@@ -0,0 +1,69 @@
+# Foundations: Mindset and Systems
+
+Inspired by principles from *Refactoring UI* by Adam Wathan & Steve Schoger. Paraphrased into the maintainer's own words; the original prose, illustrations, and examples are in the book — refactoringui.com.
+
+---
+
+## Build Real Features Before Designing the App
+
+- Don't open the design tool with "the app" in mind — start with a single feature you can actually ship
+- Navbars, sidebars, and shells should emerge from the features, not be picked first
+- "Designing the app" usually means picking a layout shell with no real content, which leads to dead ends
+
+## Sketch Rough Before Going Polished
+
+- Start with low-fidelity drawings — pencil, marker, or rough boxes in any tool
+- Use a tool that physically prevents fine detail (a thick pen, a low-resolution canvas) to lock yourself out of polish too early
+- Move to high-fidelity only when the rough concept is settled
+- Wireframing tools that already look like polished UI tend to stall this process
+
+## Cycle Between Designing and Building
+
+- Design only what you're going to build right now; don't draft the whole app at once
+- Short cycles — design a feature, build it, ship it, decide what's next
+- When in doubt, cut features; a complete simple version beats a half-built complex one
+- Save scope expansions for the next version
+
+## Defining a Project's Voice
+
+A project's "feel" is the sum of small consistent choices. Decide these together so they reinforce each other:
+
+**Type choice signals tone:**
+- Serif → editorial, traditional, considered
+- Geometric / rounded sans-serif → friendly, casual
+- Neutral sans-serif → quiet, professional, modern
+
+**Color signals associations:**
+- Cool blues → reliability, calm
+- Warm yellows / golds → warmth, premium feel
+- Pinks → playful, less serious
+
+**Border radius signals formality:**
+- Sharp / no radius → serious, technical
+- Pronounced rounding → soft, friendly
+
+**Copy register signals personality:**
+- "An error occurred" reads as formal
+- "Something broke on our end" reads as casual
+
+Every project decision should reinforce the same tone — consistency is what makes a project feel intentional rather than thrown together.
+
+## Decide Once: Pre-Build Your Systems
+
+Before picking values per-screen, define a small fixed menu of options to choose from. This eliminates per-decision fatigue and produces consistency by default.
+
+Suggested coverage:
+
+- **Type sizes:** ~8–10 hand-picked values
+- **Type weights:** typically 2 (a regular and a bold)
+- **Colors:** primary, neutrals (8–10 shades each), and 3–5 accent colors with shades
+- **Spacing:** ~10–15 values on a non-linear scale
+- **Shadows:** ~5 levels (from barely raised to floating)
+- **Border radius:** 3–5 options (none → fully rounded)
+- **Border widths:** 2–3 options
+
+## Choose by Elimination, Not by Search
+
+- Don't try to find "the perfect value" — start from the system and work by elimination
+- Too big? Try the next smaller. Too pale? Step darker. Too close to white? Step toward the next shade
+- A system makes design feel like a multiple-choice exam instead of an open-ended search

package/skills/refactoring-ui/references/02-page-mechanics.md

@@ -0,0 +1,204 @@
+# Page Mechanics: Hierarchy, Spacing, Typography
+
+Inspired by principles from *Refactoring UI* by Adam Wathan & Steve Schoger. Paraphrased into the maintainer's own words; the original prose, illustrations, and examples are in the book — refactoringui.com.
+
+---
+
+## Hierarchy Is the Most Important Tool
+
+- Every element on a page is either competing for attention or supporting something else
+- Good design isn't making everything stand out — it's making the *right* things stand out
+- If everything is emphasized, nothing is
+
+## Use Weight and Color, Not Just Size
+
+Three tools for hierarchy, in order from heaviest hammer to most subtle:
+
+1. **Font size** — most obvious. Use sparingly for big differences.
+2. **Font weight** — bold reads as important; great for same-size emphasis.
+3. **Color contrast** — use a 3-tier system:
+   - Primary: near-black for main content
+   - Secondary: mid-grey for supporting text
+   - Tertiary: lighter grey for placeholder/disabled/least important
+
+**Avoid font weights below 400 in UI** — thin/light weights look bad at small sizes on screens.
+
+## Tinted Greys for Colored Surfaces
+
+- Don't reduce text opacity to fake grey on a colored background — desaturates and looks muddy
+- Hand-pick a color with the same hue as the background, but adjusted lightness/saturation
+- The result reads as "grey within that color family" rather than as actual grey
+
+## Reduce the Competition Instead of Boosting the Star
+
+- When you want one thing to pop, often the right move is to push down everything around it — not push the primary up further
+- Reducing contrast on secondary elements preserves the visual balance and makes the primary read clearly
+- Cheaper than adding more weight/size/color to the primary
+
+## Labels: Skip, Combine, or Subordinate
+
+**Skip the label when context already tells you:**
+- An email address, a phone number, a date — format alone makes it obvious
+- A profile bio doesn't need "Bio:"
+
+**Fold label and value into a phrase:**
+- "12 left in stock" beats "In stock: 12"
+- "3 bedrooms" beats "Bedrooms: 3"
+
+**Make the label secondary when you do need it:**
+- Smaller and lighter than the value
+- The value is the content; the label is metadata
+
+## Semantics Are Not the Same as Visual Size
+
+- `<h1>`–`<h6>` carry document semantics, not visual rules
+- An `<h1>` may visually be smaller than surrounding body text in the right context
+- An `<h3>` sidebar title might be the same size as body, just bolder
+- Style by visual hierarchy, not by element level
+
+## Icons Are Visually Heavier Than Text
+
+- An icon at the same size as text reads as heavier
+- Use a softer color for icons next to text — don't reach for the same near-black as body text
+- Increase the text contrast and dim the icon, rather than the reverse
+
+## Borders Get Thicker as Their Contrast Drops
+
+- A barely-visible border becomes more readable when made slightly thicker
+- A thicker low-contrast border often beats a thin high-contrast one
+- Applies to dividers, table edges, card outlines
+
+## Button Tiers
+
+| Tier | Style | Use |
+|---|---|---|
+| Primary | Solid + high-contrast fill | The main action on the page |
+| Secondary | Outline or low-contrast fill | Supporting actions |
+| Tertiary | Link-style (no background or border) | Minor or repeating actions |
+| Destructive | Secondary style + confirm step | Delete, remove, revoke |
+
+- One primary action per page is the rule of thumb
+- Don't make destructive the primary — render as secondary, then confirm the action
+
+---
+
+## Generous Spacing as the Default
+
+- Default to *more* white space than feels right; trim it later if needed
+- Most UIs suffer from too little spacing, not too much
+- Dense feels noisy; generous feels organized
+
+## A Spacing Scale, Not Arbitrary Pixels
+
+- Define a non-linear spacing scale up front; pick from it
+- Anchor near 16px (a common base unit)
+- Adjacent values should differ by at least ~25% — otherwise they look almost identical
+- Sample non-linear scale: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128, 192, 256, 384, 512, 640, 768
+
+## Don't Stretch by Default
+
+- A short form does not need full-width inputs
+- If an element is naturally 200px wide, let it be 200px — don't reflow to 600px
+- Full-width is a deliberate choice, not a fallback
+
+## Design at the Real Size
+
+- For small components (modals, cards, widgets), shrink the canvas
+- Working at ~400px forces honest decisions about scale
+- Zooming out on a 1440px canvas makes elements feel more generous than they actually are
+- Mobile-first: design at 320–400px first, expand from there
+
+## Columns Beat Stretched Rows
+
+- When content gets too wide and elements feel diluted, introduce columns
+- A two-column settings page reads better than a settings page where every form field stretches edge-to-edge
+
+## Sidebars Use Fixed Widths
+
+- Sidebars in pixels (e.g., 240px) — not percentages
+- 20% sidebars become tiny on small screens and huge on large ones
+- Use `max-width` on content columns, not percentage grid columns
+- Percentages are for responsive *images* and grid cells, not UI chrome
+
+## Big Things Shrink More Than Small Things
+
+- A 45px headline on desktop should drop to roughly 20–24px on mobile, not just half
+- Shrink larger elements proportionally more
+- Button padding does *not* scale linearly with font:
+  - 16px font + 12px vertical padding looks balanced
+  - Bumping font to 24px doesn't mean padding becomes 18px — often padding stays close to original
+
+## Group With Space, Not Boxes
+
+- More space *around* a group than *within* it (Law of Proximity)
+- A form section header should have more room above it than below it
+- Labels should be closer to their own input than to the input above or below
+
+## Spacing Sanity Checklist
+
+- [ ] Does the spacing show what belongs together?
+- [ ] Is there more space between groups than within groups?
+- [ ] Is the label closer to its own input than to the next input?
+- [ ] Does the layout communicate grouping without borders or backgrounds?
+
+---
+
+## Hand-Pick Your Type Scale (Don't Use Modular Ratios)
+
+- Modular scales (e.g., 1.25× ratio) produce fractional pixels and useless intermediate sizes
+- Hand-pick ~8–10 sizes that actually serve real use cases
+- Sample scale: 12, 14, 16, 18, 20, 24, 30, 36, 48, 60, 72px
+- Each size should feel clearly different from its neighbors
+
+## Use px or rem — Avoid em for Type
+
+- `em` is relative to the parent's font size; nesting compounds unpredictably
+- `px` or `rem` (relative to root) keep type sizes predictable
+- `em` is fine for things like padding/margin that should scale with font, but not for the type scale itself
+
+## Shopping for a Body Font
+
+- On Google Fonts, filter by "10+ styles" — drops the bottom ~85% in one move
+- Multiple weights/styles signal a font designed seriously
+- For UI, prefer neutral sans-serif (Helvetica-style) over geometric or humanist extremes
+- A system stack (`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto`) is a safe fallback
+- Avoid condensed fonts and fonts with very short x-heights for body text
+
+## Comfortable Line Length
+
+- Target: ~45–75 characters per line
+- Equivalent: ~20–35em of width
+- Constrain paragraph width even inside a wider container
+- Too wide → eyes lose track of the next line; too narrow → too many breaks
+
+## Align Mixed Sizes by Baseline
+
+- When two elements with different font sizes sit side by side, align by baseline (bottom of text)
+- Vertical centering of mixed sizes makes the smaller text look too high
+
+## Line-Height Inversely Tracks Size
+
+- Body text in narrow columns: ~1.5
+- Wider columns: closer to 2.0
+- Large headlines: ~1.0 or slightly tighter
+- Smaller text needs more space between lines; larger text needs less
+
+## Link Styling Depends on Density
+
+- In link-heavy contexts (sidebar navs, lists), drop the colored underline — use heavier weight or darker shade instead
+- Color on every link reads as noise when most things are links
+- Footer-style "ancillary" links: color/underline only on hover
+- Save the high-contrast blue for inline body links that need to stand out
+
+## Text Alignment by Use
+
+- **Left:** the default for most text in LTR languages
+- **Center:** only short blocks (≤2–3 lines) — never a paragraph
+- **Right:** numbers in tables (so digits and decimals line up)
+- **Justified:** only with hyphenation enabled — without it, big awkward gaps
+
+## Letter-Spacing
+
+- **Body fonts at headline sizes:** tighten letter-spacing slightly (negative tracking) — body fonts are tuned for small sizes, look loose at large sizes
+- **All-caps text:** always loosen letter-spacing — caps are harder to read, extra space helps
+- Never tighten body text or all-caps — kills legibility

package/skills/refactoring-ui/references/03-visual-treatment.md

@@ -0,0 +1,242 @@
+# Visual Treatment: Color, Depth, Images
+
+Inspired by principles from *Refactoring UI* by Adam Wathan & Steve Schoger. Paraphrased into the maintainer's own words; the original prose, illustrations, and examples are in the book — refactoringui.com.
+
+---
+
+## HSL Is the Right Model for UI Color
+
+HSL (Hue, Saturation, Lightness) gives intuitive control:
+
+- **Hue:** 0°=red, 60°=yellow, 120°=green, 180°=cyan, 240°=blue, 300°=magenta
+- **Saturation:** 0%=grey (no color), 100%=fully vivid
+- **Lightness:** 0%=black, 50%=pure color, 100%=white
+
+**HSL ≠ HSB (HSV).** HSB's "brightness" at 100% still gives a vivid color; HSL's lightness at 100% is always white. Don't conflate them.
+
+## Building a Complete Palette
+
+Plan for more colors than you'd guess:
+
+- **Greys:** 8–10 shades (text, backgrounds, borders, UI chrome)
+- **Primary brand color:** 5–10 shades
+- **Accent set:** typically 3–5 named colors × 5–10 shades each
+  - Red (danger, error, destructive)
+  - Yellow (warning, caution)
+  - Green (success, positive)
+  - Others as needed (blue for info, purple, etc.)
+
+That can mean ~10 colors × ~10 shades = 100 values. Define them all once, up front.
+
+## Skip Preprocessor `lighten()` / `darken()`
+
+- `lighten(blue, 20%)` mixes white into the color — produces washed-out results
+- `darken(blue, 20%)` mixes black — produces muddy, lifeless results
+- Hand-pick shades using HSL — better results every time
+
+## Building a 9-Step Shade Scale (100–900)
+
+Step by step:
+
+1. **Pick the base** (500): should work as a button background
+2. **Pick the darkest** (900): should work as text on light bg
+3. **Pick the lightest** (100): should work as a tinted background
+4. **Fill in 700:** roughly halfway between 500 and 900
+5. **Fill in 300:** roughly halfway between 100 and 500
+6. **Fill the gaps** (200, 400, 600, 800) by eye — adjusting until the steps feel even
+
+## Bump Saturation as Lightness Moves Away from 50%
+
+- Moving lightness toward 0% or 100% in pure HSL drains apparent vividness
+- Counter it: increase saturation as you push lightness up or down
+- Very light shades (lightness 90–95%): bump saturation noticeably
+- Very dark shades (lightness 15–25%): bump saturation to keep richness
+- Without this, light shades look washed out and dark shades look muddy
+
+## Rotate Hue Slightly When Lightening or Darkening
+
+- Pure-hue lightening/darkening looks artificial; shifting hue a bit produces more natural shades
+- Toward lighter: rotate toward the nearest "bright anchor" (60°, 180°, 300°)
+- Toward darker: rotate toward the nearest "dark anchor" (0°, 120°, 240°)
+- Cap the rotation at ~20–30° — beyond that the color reads as a different one entirely
+- Mimics how real pigments behave when tinted or shaded
+
+## Greys Don't Need to Be Pure Grey
+
+- Pure 0%-saturation grey often feels clinical and bland
+- **Cool greys:** small amount of blue saturation → modern, professional
+- **Warm greys:** small amount of yellow/orange saturation → inviting, human
+- Match the temperature of your greys to the rest of your palette
+
+## Accessible Contrast (WCAG)
+
+- **Small text (<~18px normal weight, <~14px bold):** at least 4.5:1
+- **Large text (≥~18px normal, ≥~14px bold):** at least 3:1
+- Dark text on white passes more easily than white text on a colored bg
+
+## When White-on-Colored Fails Contrast
+
+- Try dark text on a *light tinted* version of the same brand color
+- Example: dark navy text on pale blue — same brand, much higher contrast
+- Often more sophisticated visually than white-on-saturated
+
+## Colored Text on Colored Backgrounds
+
+- White text on a vivid bright button often fails contrast
+- Instead of darkening the background, shift the *text* hue toward a bright anchor (rotate toward yellow/60°)
+- Yellow text on a dark orange button can read more clearly than white because yellow is inherently brighter
+
+## Color Cannot Be the Only Signal
+
+- ~8% of males cannot distinguish red/green by color alone
+- Always pair color with a second signal:
+  - Icon (checkmark, warning triangle, X)
+  - Shape difference
+  - Text label
+  - Position or strong contrast difference
+- Applies to: status badges, error states, success messages, alert levels, charts
+
+---
+
+## Light Source Convention
+
+- Simulated depth in a UI assumes the light source sits **above** the screen
+- Users naturally look at screens from a slightly downward angle
+- Every shadow, edge, and inset should respect that single "sun"
+
+## Raised Elements
+
+To make an element appear lifted off the page:
+
+- **Lighter top edge:** a top border or top inset shadow in a lighter shade
+- **Small dark shadow below:** the element's cast shadow on the surface
+- Hand-pick the lighter color — semi-transparent white (`rgba(255,255,255,0.x)`) desaturates the underlying color and looks fake
+
+## Inset Elements
+
+To make an element appear pressed into the page:
+
+- **Lighter bottom edge:** bottom border or bottom inset shadow in a lighter shade
+- **Small dark inset shadow at top:** simulates shadow falling into the well
+- Same rule: hand-pick the light color rather than using transparent white
+
+## Five-Level Shadow System
+
+Define ~5 shadow levels (similar to Material Design's elevation):
+
+- **Level 1 — barely raised:** very small blur, tiny offset
+- **Level 2 — slightly higher:** modest blur and offset
+- **Level 3 — default card:** medium blur, medium offset
+- **Level 4 — modal / dropdown:** large blur, larger offset
+- **Level 5 — closest to viewer:** very large blur, biggest offset (tooltips, popovers)
+
+Rule of thumb: small blur reads as slightly raised, large blur reads as floating close to the viewer.
+
+## Shadows React to Interaction
+
+- **On drag (element "picked up"):** shadow grows (blur and offset increase) — feels like the element moved closer to the user
+- **On click/press (element pressed in):** shadow shrinks or disappears — feels pushed into the surface
+- Tactile feedback without animation
+
+## Compound Shadows: Direct + Ambient Light
+
+Real objects cast two shadow layers:
+
+1. **Direct light shadow** (umbra): large, soft, big offset, big blur — from the primary light source
+2. **Ambient light shadow** (penumbra): tight, dark, small offset, small blur — from scattered ambient light
+
+For UI:
+
+- Shadow 1: large blur, large offset, low opacity (direct)
+- Shadow 2: small blur, small offset, higher opacity (ambient)
+
+At higher elevations, the ambient shadow becomes more subtle relative to the direct shadow.
+
+## Depth Without Shadows (Flat Aesthetic)
+
+When shadows aren't appropriate:
+
+- **Lighter = closer, darker = further** — opposite of real-world intuition, but works visually
+- Solid no-blur "shadows": `box-shadow: 4px 4px 0 #000` for a retro/flat look
+- These define edges without implying a light source
+
+## Layering Through Element Overlap
+
+- Overlap one element across the boundary of another to create a clear sense of layers
+- Example: a card straddling a dark hero and a white content area below
+- Example: an avatar that overlaps the edge of a card — depth without shadow
+
+## Halo Borders to Separate Adjacent Images
+
+- When images touch each other or a busy background, edges clash
+- Add a border in the **same color as the background** behind the image
+- That "invisible" border (sometimes called a halo) creates separation without a visible line color
+
+---
+
+## Use Real Content From the Start
+
+- Never design with placeholder images — grey boxes lie about how the layout actually feels
+- Real photos differ in aspect, brightness, and busyness — design must work with reality
+- Hire a photographer or use quality stock services (e.g., Unsplash)
+
+## Putting Text on Top of an Image
+
+Four reliable techniques:
+
+**1. Semi-transparent overlay**
+- Dark overlay for light-colored text
+- Light overlay for dark-colored text
+- Tune the overlay opacity until contrast is comfortable
+
+**2. Reduce image contrast / shift brightness**
+- Lower contrast on the image so text has a more uniform background
+- Brighten or darken globally to give a consistent canvas
+
+**3. Recolor the image**
+- Desaturate, then apply a solid color via "multiply" blend mode
+- Result: a single-tone image that text reads cleanly on top of
+
+**4. Soft halo behind the text**
+- Big blur, no offset text-shadow behind the text
+- Best for short text (headlines, labels), not paragraphs
+
+## Don't Just Scale Tiny Icons Up
+
+- Icons drawn at 16–24px look chunky and blurry when stretched 3–4×
+- At larger sizes, put the icon inside a **shaped container** (circle, rounded square)
+- Scale the container up; keep the icon at native size (or only slightly larger)
+- Adds polish, avoids the "blown-up icon" problem
+
+## Screenshots in Marketing/Documentation
+
+The problem: scaling shrinks text below readability.
+
+- At 70% scale, 16px font ≈ 11px — already getting unreadable
+- At 50% scale, 16px font = 8px — illegible
+
+What works:
+
+1. Use a tablet/narrow-layout screenshot — scales better than a full desktop one
+2. Take a partial screenshot — crop to the relevant area
+3. Draw a simplified version — strip most UI, keep what matters
+4. Don't depend on the viewer being able to read the text in a thumbnail
+
+## Favicons Need to Be Redrawn, Not Shrunk
+
+- A 128px logo shrunk to 16px loses too much detail
+- Redraw at the target size (16×16, 32×32) from scratch
+- 1–2 elements only; usually just the icon mark, not the wordmark
+- Test at 1× actual size while designing — what reads at 128px is often noise at 16px
+
+## User-Uploaded Images: Two Problems
+
+**Aspect ratio:** uploads won't match your layout's expected proportions.
+- Fixed-size container
+- `background-size: cover` (or CSS `object-fit: cover`)
+- Let the engine center and crop
+
+**Background bleed:** white-bg images dissolve into white page bgs.
+- Don't use a hard border — too heavy
+- Instead, an inset box-shadow: `box-shadow: inset 0 0 0 1px rgba(0,0,0,0.1)`
+- Soft inner ring that defines the edge without a visible border color