@maccesar/aiskills 1.9.2 → 1.10.0

package/skills/refactoring-ui/references/04-polish.md

@@ -0,0 +1,96 @@
+# Polish: Finishing Touches and Sharpening Intuition
+
+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.
+
+---
+
+## Replace Default Bullets with Meaningful Icons
+
+- Default disc bullets feel generic and low-effort
+- Swap for icons that match the content:
+  - Checkmarks for feature lists or completed items
+  - Arrows for sequential or directional lists
+  - Content-specific icons (lock for "secure", globe for "worldwide")
+- Adds visual interest *and* reinforces meaning at the same time
+
+## Big Quotation Marks as Decorative Elements
+
+- For testimonials and pull quotes, quotation marks can become design elements rather than punctuation
+- Make them large, colorful (accent color), positioned prominently
+- The quote mark is now part of the visual design
+
+## Style Links With Intention
+
+Two paths depending on context:
+
+1. **Color + weight:** brand-colored link with a slightly heavier weight than surrounding text
+2. **Thick colorful underline:** a 2–4px border-bottom in an accent color that overlaps the lower portion of the text — clearly a link, visually distinctive
+
+## Custom Checkbox and Radio Styling
+
+- Browser default inputs look generic and break brand identity
+- Build custom-styled checkboxes/radios using your brand color for the checked state
+- Common pattern: custom checkbox = colored fill + checkmark SVG
+- Worth the extra markup — defaults feel like 1996 every time
+
+## Color Accents on Edges
+
+A short, thick accent-color stripe is a high-impact, low-effort touch. Common placements:
+
+- **Top of a card** — a colored bar at the top edge
+- **Left side of an active nav item** — communicates "you are here"
+- **Left side of an alert message** — color-codes the alert type (red=danger, yellow=warning, green=success)
+- **Under a headline** — a short thick underline in brand color
+- **Top of the entire page** — a thin strip of color across the very top
+
+These add brand identity without adding complexity.
+
+## Going Beyond a Plain Background
+
+Options when "white" feels boring:
+
+1. **Solid color shift:** switch from white to a brand-tinted neutral
+2. **Gradient:** between two hues no more than 30° apart on the color wheel — close = natural, far = jarring
+3. **Low-contrast repeating pattern:** subtle dots, lines, or hatching at low opacity
+4. **Geometric shapes / blobs:** abstract colored shapes at low opacity behind content
+
+Gradient rule of thumb: keep the two hues within ~30° of each other for a natural blend.
+
+## Empty States Deserve Real Design
+
+- Empty UIs look broken or confusing — and they're often the *first* thing new users see
+- Design the empty state as deliberately as the populated one
+
+A good empty state has:
+
+- A contextually relevant illustration or icon
+- A short, friendly explanation of what belongs here
+- A clear next-step CTA (e.g., "Add your first project")
+
+Companion rule: **hide UI that has nothing to operate on**
+
+- Tabs with no content, filters with no items, pagination with one page — all read as broken
+- Don't render those elements until there's content to make them useful
+
+## Alternatives to Borders
+
+Borders are overused. Try:
+
+1. **Box shadow:** `box-shadow: 0 1px 3px rgba(0,0,0,0.1)` — separates without a hard line
+2. **Two background colors:** alternating backgrounds communicate sections without lines
+3. **More space:** sometimes the right answer is just more white space
+
+## Beyond the Generic Pattern
+
+Don't reach for the standard widget when something more engaging fits:
+
+- **Enriched dropdowns:** add icons, sections, descriptions, two-column layouts inside dropdowns
+- **Hierarchy inside table cells:** instead of equal-weight columns, give each cell its own primary/secondary tier (large dark for the main value, small grey for secondary)
+- **Selectable cards instead of radios:** for option groups, replace radio buttons with styled card options that highlight on selection — easier to scan, more inviting
+
+## Sharpening Design Intuition Over Time
+
+Two practices that compound:
+
+1. **Study the unintuitive choices in good UIs.** Find polished products you admire and ask *"why did they do that?"* — focus on choices you wouldn't have made yourself. Those are the ones worth learning from.
+2. **Rebuild interfaces without DevTools.** Pick a UI you admire and recreate it from scratch — no inspecting the original. Forces real decisions instead of copying values.

package/skills/stitch-showcase/SKILL.md

@@ -13,6 +13,10 @@ Converts Google Stitch exports (zips with `code.html` + `screen.png`) into a nav
 
 Scripts require Python 3.8+. No external dependencies (stdlib only).
 
+## Script paths
+
+All commands below use `<SKILL_DIR>/scripts/...` as a placeholder. Replace `<SKILL_DIR>` with the absolute "Base directory for this skill" shown in the system message when this skill loads (e.g. `~/.claude/plugins/cache/<plugin>/<version>/skills/stitch-showcase` for plugin installs, or `~/.claude/skills/stitch-showcase` for standalone installs). Do not assume `~/.claude/skills/...` — the path differs by install type.
+
 ## Workflow: Four Modes
 
 ```dot
@@ -47,7 +51,7 @@ Steps:
 1. Identify the source path from the user's message
 2. Run the build script — **nothing else**:
    ```bash
-   python ~/.claude/skills/stitch-showcase/scripts/build_showcase.py /path/to/source
+   python <SKILL_DIR>/scripts/build_showcase.py /path/to/source
    ```
 3. Parse the script output to get the `showcase/` path
 4. Open the showcase in the default browser:
@@ -61,8 +65,8 @@ Steps:
 Only ask `--type` or `--name` if the **script fails** or the **user explicitly wants to override**:
 ```bash
 # Only if script fails to detect type or user requests it
-python ~/.claude/skills/stitch-showcase/scripts/build_showcase.py /path/to/source --type mobile
-python ~/.claude/skills/stitch-showcase/scripts/build_showcase.py /path/to/source --name "My App" --type mobile
+python <SKILL_DIR>/scripts/build_showcase.py /path/to/source --type mobile
+python <SKILL_DIR>/scripts/build_showcase.py /path/to/source --name "My App" --type mobile
 ```
 
 ## Mode 2: Enrich (on-demand — user asks)
@@ -75,7 +79,7 @@ Steps:
 1. Find the source folder (from the user's message or the project's `showcase.json`)
 2. Run `--extract-text` to get screen summaries:
    ```bash
-   python ~/.claude/skills/stitch-showcase/scripts/build_showcase.py /path/to/source --extract-text
+   python <SKILL_DIR>/scripts/build_showcase.py /path/to/source --extract-text
    ```
    This generates `screen_summaries.txt` — a compact text file with visible text from all screen HTMLs.
 3. Read the existing `DESIGN.md` (in the source folder) + `screen_summaries.txt`
@@ -87,7 +91,7 @@ Steps:
 6. **Verify colors/fonts**: Scan the screen HTMLs for hex colors in CSS variables and font families. Update `## Colors` and `## Typography` sections if they're missing or incomplete.
 7. Re-run the build to regenerate HTMLs with enriched data:
    ```bash
-   python ~/.claude/skills/stitch-showcase/scripts/build_showcase.py /path/to/source
+   python <SKILL_DIR>/scripts/build_showcase.py /path/to/source
    ```
 8. Done — tell the user the showcase has been updated with improved descriptions
 
@@ -136,13 +140,13 @@ Steps:
 
 ```bash
 # Structural components (navbar, footer, sidebar, tabbar)
-python ~/.claude/skills/stitch-showcase/scripts/apply_canonical.py /path/to/showcase/assets/ navbar home_screen
+python <SKILL_DIR>/scripts/apply_canonical.py /path/to/showcase/assets/ navbar home_screen
 
 # Atomic components (button, input, heading, etc.)
-python ~/.claude/skills/stitch-showcase/scripts/apply_canonical.py /path/to/showcase/assets/ button home_screen
+python <SKILL_DIR>/scripts/apply_canonical.py /path/to/showcase/assets/ button home_screen
 
 # Target specific screens only
-python ~/.claude/skills/stitch-showcase/scripts/apply_canonical.py /path/to/showcase/assets/ navbar home_screen --targets login settings profile
+python <SKILL_DIR>/scripts/apply_canonical.py /path/to/showcase/assets/ navbar home_screen --targets login settings profile
 ```
 
 4. Rebuild the showcase: `build_showcase.py /path/to/source`
@@ -177,13 +181,13 @@ The catalog is generated automatically as part of every build. Open `catalog.htm
 
 ```bash
 # Point to the project root — the script discovers the source automatically
-python ~/.claude/skills/stitch-showcase/scripts/build_showcase.py /path/to/project
+python <SKILL_DIR>/scripts/build_showcase.py /path/to/project
 
 # Or point directly to the folder with zips/screens
-python ~/.claude/skills/stitch-showcase/scripts/build_showcase.py /path/to/project/stitch
+python <SKILL_DIR>/scripts/build_showcase.py /path/to/project/stitch
 
 # Single mega-zip (zip containing all screens as subfolders)
-python ~/.claude/skills/stitch-showcase/scripts/build_showcase.py /path/to/export.zip
+python <SKILL_DIR>/scripts/build_showcase.py /path/to/export.zip
 ```
 
 ### Flags

package/skills/refactoring-ui/references/01-design-process.md

@@ -1,72 +0,0 @@
-# Ch1 — Starting from Scratch
-
-Source: "Refactoring UI" by Adam Wathan & Steve Schoger
-
----
-
-## Feature-First Design
-
-- Design actual features, not shells, navbars, or layouts first
-- Pick one real feature and design it end-to-end before thinking about navigation
-- The shell and layout emerge naturally from the features — don't force it first
-- Resist the urge to design "the app" — design what people will actually use
-
-## Low-Fidelity First (Thick Sharpie Trick)
-
-- Start with low-fidelity mockups — details don't matter at this stage
-- Use a thick Sharpie (or similar): makes it physically impossible to add fine details
-- Sketch ideas, not pixels — get the general layout and content blocks right
-- Avoid wireframing tools that tempt you into making polished designs too early
-- Don't move to high-fidelity until the concept is locked
-
-## Work in Cycles, Be a Pessimist
-
-- Only design what you're ready to build right now
-- Work in short design-then-build cycles, not one giant design phase
-- Be a pessimist: cut features before building, not after
-- A simple, complete experience beats a complex, half-built one
-- Add features to the next version; ship the core first
-
-## Choose a Personality
-
-Design decisions that define personality:
-
-**Font choice:**
-- Serif → classic, elegant, literary (e.g., law firms, newspapers)
-- Rounded sans-serif → playful, friendly, approachable
-- Neutral sans-serif → plain, professional, clean
-
-**Color:**
-- Blue → safe, familiar, trustworthy
-- Gold/yellow → luxurious, sophisticated
-- Pink → fun, not-too-serious
-
-**Border radius:**
-- Small or none → formal, serious
-- Large → playful, friendly
-
-**Language register:**
-- "An error occurred" → formal
-- "Uh oh, something broke!" → casual and approachable
-
-Every choice should reinforce the same personality — be consistent.
-
-## Pre-Define Systems Before Designing
-
-Define your system up front; make decisions once instead of every time:
-
-- **Font sizes:** 8-10 values (type scale)
-- **Font weights:** usually 2 (normal 400, bold 600/700)
-- **Colors:** 8-10 shades per color, plus primary, greys, accents
-- **Spacing:** 10-15 values on a non-linear scale
-- **Box shadows:** 5 options (small, medium, large, extra-large, inner)
-- **Border radius:** 3-5 options (none, small, medium, large, full)
-- **Border widths:** 2-3 options
-
-**Benefit:** When you need to make a decision, you're choosing from a small set, not from infinity. Eliminates decision fatigue.
-
-## Process of Elimination
-
-- Don't try to "find the perfect value" — start from a set and eliminate
-- Too big? Try the next smaller option. Too close to white? Try the next shade darker.
-- Systems make design systematic, not artistic guesswork

package/skills/refactoring-ui/references/02-visual-hierarchy.md

@@ -1,84 +0,0 @@
-# Ch2 — Hierarchy is Everything
-
-Source: "Refactoring UI" by Adam Wathan & Steve Schoger
-
----
-
-## Visual Hierarchy is the #1 Design Tool
-
-- Every element on a page is either competing for attention or supporting something else
-- Good design is not about making everything stand out — it's about 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 of subtlety):
-1. **Font size** — most obvious, use sparingly for big differences
-2. **Font weight** — bold text reads as important; good for same-size emphasis
-3. **Color** — use dark/grey/lighter-grey to create a 3-tier system:
-   - Primary: near-black for main content
-   - Secondary: mid-grey for supporting text
-   - Tertiary: lighter grey for placeholder/disabled/least important
-
-**Never use font weights below 400** for UI text — thin/light weights look bad at small sizes on screens.
-
-## Grey Text on Colored Backgrounds
-
-- Don't reduce text opacity to create grey on a colored background — this desaturates and looks muddy
-- Instead: hand-pick a color with the same hue as the background, but adjusted lightness/saturation
-- Pick a color that feels like a "grey" version within that color family, not an actual grey
-
-## Emphasize by De-Emphasizing Competitors
-
-- When you want one element to stand out, try making everything around it less prominent instead of making it bigger/bolder
-- Reduce contrast on secondary elements rather than adding more styling to primary ones
-- This is often more effective than adding emphasis — it preserves the visual balance
-
-## Labels: When to Skip, Combine, or Subordinate
-
-**Skip the label when:**
-- Format makes it obvious (e.g., an email address, a phone number, a date)
-- Context makes it obvious (e.g., a profile page bio doesn't need "Bio:" label)
-
-**Combine label and value:**
-- "12 left in stock" instead of "In stock: 12"
-- "Bedrooms: 3" → "3 bedrooms"
-
-**Treat label as secondary:**
-- When you do need a label, make it smaller/lighter than the value
-- The value is what matters; the label is supporting metadata
-
-## HTML Heading Elements ≠ Visual Size
-
-- `<h1>`–`<h6>` are semantic, not visual
-- An `<h1>` might visually be smaller than surrounding text if the context calls for it
-- An `<h3>` sidebar title might be the same size as body text, just bolder
-- Style headings based on visual hierarchy, not element level
-
-## Icons Are Heavy — Reduce Their Contrast
-
-- Icons carry more visual weight than text at the same size
-- To balance icons with surrounding text, use a softer/lighter color for the icon
-- Don't use the same high-contrast color you use for body text — icons will dominate
-- Reduce icon contrast; increase text contrast if needed
-
-## Increase Border Width for Low-Contrast Elements
-
-- When a border is barely visible (low contrast), making it thicker compensates
-- A thicker, slightly lighter border can read better than a thin, barely-there one
-- This is especially relevant for dividers, table borders, and card edges
-
-## Button Hierarchy
-
-Four tiers of buttons:
-
-| 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/border) | Least important actions |
-| Destructive | Secondary style + confirmation step | Delete, remove, revoke |
-
-- A page should rarely have more than one primary button
-- Destructive actions should NOT use red as primary — make them secondary, then confirm
-- Hierarchy between buttons prevents visual noise and guides users to the right action

package/skills/refactoring-ui/references/03-layout-spacing.md

@@ -1,69 +0,0 @@
-# Ch3 — Layout and Spacing
-
-Source: "Refactoring UI" by Adam Wathan & Steve Schoger
-
----
-
-## Start with Too Much White Space
-
-- Default to more white space, then remove it — don't add white space after the fact
-- Most UIs suffer from too little spacing, not too much
-- Dense UIs feel busy and hard to scan; generous spacing feels calm and organized
-
-## Spacing Scale
-
-- Use a defined, non-linear spacing scale — not arbitrary pixel values
-- Base value: **16px** is a natural anchor point
-- Adjacent values on the scale should differ by at least 25%
-- Example scale (non-linear): 4, 8, 12, 16, 24, 32, 48, 64, 96, 128, 192, 256, 384, 512, 640, 768
-- The non-linearity matters: you want clearly distinct values, not ones that look nearly the same
-
-## Use Only the Space You Need
-
-- Don't stretch elements to fill the full container by default
-- Short forms don't need full-width inputs
-- If an element's natural width is 200px, let it be 200px — don't stretch to 600px
-- Full-width is a choice, not a default
-
-## Shrink Your Canvas for Small Interfaces
-
-- When designing small components (modals, cards, widgets), shrink the canvas
-- Working at ~400px forces you to think about the actual scale
-- Zooming out on a 1440px canvas to see a card is deceptive — elements feel more generous than they are
-- Mobile-first approach: design at 320-400px first, then expand
-
-## Split into Columns Instead of Stretching
-
-- When content is too wide or elements feel stretched, introduce columns
-- A two-column layout for a settings page beats stretching form fields across the full width
-- Use columns to create denser, more structured layouts without sacrificing usability
-
-## Fixed Widths for Sidebars
-
-- Sidebars should use fixed pixel widths, not percentages
-- A sidebar at `240px` stays consistent; at `20%` it becomes tiny or huge at different breakpoints
-- Use `max-width` constraints for content columns rather than percentage-based grid columns
-- Percentage widths work for responsive images and grid cells — not for UI chrome
-
-## Responsive Scaling: Large Elements Shrink Faster
-
-- Large headline that is 45px on desktop → should be 20-24px on mobile
-- The ratio of reduction is not 1:1 — large elements shrink proportionally more
-- Button padding does not scale proportionally with font size:
-  - A button with 16px font and 12px vertical padding looks right
-  - Increasing font to 24px doesn't mean padding should become 18px
-  - Often keep padding roughly the same while increasing font
-
-## Spacing Within Groups vs. Between Groups
-
-- More space should appear **around** a group than **within** it (Law of Proximity)
-- Elements close together are perceived as related
-- A form section header should have more space above it (separating from previous section) than below it (connecting to its fields)
-- Labels should be closer to their own input than to the input above or below
-
-## Law of Proximity Checklist
-
-- [ ] Does the spacing clearly show which elements belong together?
-- [ ] Is there more space between groups than within groups?
-- [ ] Is the label closer to its own input than to adjacent inputs?
-- [ ] Does the layout communicate grouping without relying on borders or backgrounds?

package/skills/refactoring-ui/references/04-typography.md

@@ -1,70 +0,0 @@
-# Ch4 — Designing Text
-
-Source: "Refactoring UI" by Adam Wathan & Steve Schoger
-
----
-
-## Hand-Crafted Type Scale (Avoid Modular Scales)
-
-- Modular scales (e.g., 1.25× ratio) produce fractional pixel values and limited useful sizes
-- Better approach: hand-pick 8-10 sizes that actually work for your use cases
-- Example scale: 12, 14, 16, 18, 20, 24, 30, 36, 48, 60, 72px
-- Each value should feel clearly different from adjacent ones — not nearly identical
-
-## Use px or rem — Never em
-
-- `em` units are relative to the parent element's font size
-- Nesting elements with `em` compounds the sizing unpredictably
-- Use `px` or `rem` (relative to root font size only) for type scale
-- `em` is appropriate for things like `margin`/`padding` that should scale with font size, but NOT for defining the type scale itself
-
-## Choosing Fonts from Google Fonts
-
-- Filter by: "10+ styles" — this alone cuts ~85% of sans-serif fonts, leaving fewer than 50
-- Quality signal: fonts with many weights/styles are taken seriously by their designers
-- For UI: choose a neutral sans-serif (Helvetica-style, not geometric or humanist extremes)
-- System font stack (`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto`) is a safe fallback
-- Avoid condensed fonts (narrow letterforms) or fonts with very short x-heights for body text — hard to read at small sizes
-
-## Optimal Line Length
-
-- Target: **45–75 characters** per line for comfortable reading
-- Equivalent width: approximately **20–35em**
-- Limit paragraph width even when placed inside a wider content area
-- Too wide: eyes get lost tracking back to the next line
-- Too narrow: too many line breaks, disrupts reading flow
-
-## Baseline Alignment for Mixed Font Sizes
-
-- When two elements with different font sizes sit side by side, align them by **baseline** (bottom of text), not by vertical center
-- Vertical center alignment of mixed sizes looks off — the smaller text appears too high
-
-## Line-Height Rules
-
-- **Body text (narrow columns):** ~1.5 line-height
-- **Wide columns:** up to 2.0 line-height
-- **Large headlines:** ~1.0 or slightly below (they need almost no leading)
-- Rule: line-height is **inversely proportional** to font size
-  - Small text → more line-height (harder to track between lines)
-  - Large text → less line-height (already easy to track; extra space feels empty)
-
-## Styling Links
-
-- In **link-heavy UIs** (e.g., sidebars, navigation): use heavier weight or darker color instead of blue color
-- Color alone creates too much noise when everything is a link
-- **Ancillary links** (e.g., "privacy policy" in footers): only show underline/color on hover
-- Reserve high-contrast blue links for inline text where they need to stand out from surrounding prose
-
-## Text Alignment
-
-- **Left-align** for most text — the natural reading direction for LTR languages
-- **Center-align** only for short text blocks (max 2–3 lines); never center long paragraphs
-- **Right-align** numbers in tables (so decimal points and digits align vertically)
-- **Justified text:** hyphenate it — without hyphenation, justified text creates awkward gaps
-
-## Letter-Spacing Adjustments
-
-- **Headlines using wide-spaced body fonts:** tighten letter-spacing slightly (negative tracking)
-  - Body fonts are optimized for reading at small sizes; at large sizes they can feel too loose
-- **All-caps text:** always increase letter-spacing — all-caps is harder to read, extra spacing compensates
-- Never apply tight letter-spacing to body text or all-caps — it reduces legibility

package/skills/refactoring-ui/references/05-color.md

@@ -1,96 +0,0 @@
-# Ch5 — Working with Color
-
-Source: "Refactoring UI" by Adam Wathan & Steve Schoger
-
----
-
-## HSL Color Model
-
-HSL (Hue, Saturation, Lightness) is the right model for UI color work:
-
-- **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):** Different definitions of "lightness." HSB's "brightness" at 100% still gives a vivid color; HSL's lightness at 100% is always white. They are NOT interchangeable.
-
-## What Colors You Need
-
-A complete UI color system requires:
-- **Greys:** 8–10 shades (used for text, backgrounds, borders, UI chrome)
-- **Primary color:** 5–10 shades (brand color, main actions)
-- **Accent colors:** typically 3–5 colors × 5–10 shades each
-  - Red (danger, error, destructive)
-  - Yellow (warning, caution)
-  - Green (success, positive)
-  - Others as needed (blue for info, purple, etc.)
-
-This can mean 10 colors × 10 shades = 100 values. Define them all up front.
-
-## Do NOT Use Preprocessor lighten()/darken()
-
-- `lighten(blue, 20%)` just adds white or removes saturation — produces washed-out results
-- `darken(blue, 20%)` adds black — produces muddy, lifeless results
-- Define shades up front by hand using HSL — you'll get better results every time
-
-## How to Build a 9-Shade Scale (100–900)
-
-Step-by-step:
-1. **Pick your base color** (e.g., 500): should work as a button background
-2. **Pick the darkest shade** (e.g., 900): should work as dark text
-3. **Pick the lightest shade** (e.g., 100): should work as a tinted background
-4. **Fill in 700** next (halfway between 500 and 900)
-5. **Fill in 300** next (halfway between 100 and 500)
-6. **Fill remaining gaps** (200, 400, 600, 800) by eye
-
-## Saturation Must Increase as Lightness Moves from 50%
-
-- Pure HSL: as you move lightness toward 0% or 100%, the color appears less vivid
-- To compensate, **increase saturation** as lightness increases or decreases from 50%
-- Very light shades (lightness 90–95%): bump saturation up significantly
-- Very dark shades (lightness 15–25%): bump saturation up to maintain richness
-- If you don't, light shades look washed-out and dark shades look muddy
-
-## Rotate Hue for Perceptually Better Shades
-
-- Rotating hue slightly while lightening/darkening produces more natural results
-- To make a **lighter** shade: rotate hue toward the nearest "bright" color (60°, 180°, 300°)
-- To make a **darker** shade: rotate hue toward the nearest "dark" color (0°, 120°, 240°)
-- Maximum rotation: **20–30°** — more than that and the color looks completely different
-- This mimics how real pigments behave when tinted or shaded
-
-## Cool vs. Warm Greys
-
-- True neutral grey has 0% saturation — often feels clinical and bland
-- **Cool greys:** add a small amount of blue saturation (feels modern, professional)
-- **Warm greys:** add a small amount of yellow or orange saturation (feels inviting, human)
-- Match grey temperature to your overall palette's temperature
-
-## Accessible Contrast (WCAG)
-
-- **Small text (<~18px normal weight, <~14px bold):** minimum 4.5:1 contrast ratio
-- **Large text (≥~18px normal or ≥~14px bold):** minimum 3:1 contrast ratio
-- Check: dark text on white bg is easier to pass than white on dark colored bg
-
-## Accessibility Alternatives to White-on-Dark
-
-- Instead of white text on a dark colored background, try **dark text on a light tinted background**
-- Example: dark navy text on pale blue background — same brand color, much higher contrast
-- This "flip" is often more accessible and looks more sophisticated
-
-## Colored Text on Colored Background (Accessible)
-
-- White text on a vivid colored button fails contrast if the color is too bright
-- Instead of darkening the background, try **rotating the hue toward a bright anchor**
-- A gold/yellow text on a dark orange button is more legible than white because yellow is inherently brighter
-- Experiment: rotate hue toward 60° (yellow) for lighter-feeling text that still passes contrast
-
-## Never Use Color as the Only Signal
-
-- Color-blind users (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 contrast difference
-- This applies to: status badges, error states, success messages, alert levels, charts

package/skills/refactoring-ui/references/06-depth-shadows.md

@@ -1,74 +0,0 @@
-# Ch6 — Creating Depth
-
-Source: "Refactoring UI" by Adam Wathan & Steve Schoger
-
----
-
-## Light Source Convention
-
-- Light source is always **above** the interface
-- Users look at screens from a slightly downward angle
-- This is the physical convention all simulated depth should honor
-
-## Raised Elements
-
-To make an element appear raised off the page:
-- **Lighter top edge:** use a top border or top-side inset box-shadow in a lighter color
-- **Small dark box-shadow below:** simulates the shadow cast downward by the raised element
-- Pick the lighter edge color by hand — do NOT use semi-transparent white (`rgba(255,255,255,0.x)`) because it desaturates the underlying color and looks fake
-
-## Inset Elements
-
-To make an element appear pressed into the page:
-- **Lighter bottom edge:** use a bottom border or bottom-side inset box-shadow in a lighter color
-- **Small dark inset shadow at top:** simulates the shadow falling into the well
-- Same rule: hand-pick the lighter color instead of using semi-transparent white
-
-## 5-Level Shadow Elevation System
-
-Define 5 shadow levels (like Material Design's elevation system):
-- **Level 1 (almost flat):** very small blur, tiny offset — element is barely raised
-- **Level 2:** slightly larger blur and offset
-- **Level 3:** medium blur, medium offset — default "card" shadow
-- **Level 4:** large blur, larger offset — modals, dropdowns
-- **Level 5 (closest to user):** very large blur, biggest offset — tooltips, popovers in foreground
-
-Rule: small blur = slightly raised; large blur = close to the user/floating.
-
-## Shadow Response to Interaction
-
-- **On drag (element is "picked up"):** shadow grows — blur and offset increase as if the element moved closer to the user
-- **On click/press (element is pressed in):** shadow shrinks and may disappear — simulates the element being pushed into the surface
-- This gives tactile feedback without animation
-
-## Two-Part Shadow for Realism
-
-Real objects cast two kinds of shadow:
-1. **Direct light shadow** (umbra): large, soft, with big offset and big blur — from the primary light source
-2. **Ambient light shadow** (penumbra): tight, dark, with small offset and small blur — from scattered ambient light
-
-For UI shadows:
-- Shadow 1: large blur, large offset, low opacity (direct light)
-- Shadow 2: small blur, small offset, higher opacity (ambient)
-
-At higher elevations (closer to user), the ambient shadow (Shadow 2) becomes more subtle relative to Shadow 1.
-
-## Flat Design Depth Alternatives
-
-When shadows are not appropriate (flat aesthetic):
-- **Lighter = closer, darker = further** — opposite of intuition with real light, but works visually
-- Use solid, no-blur shadows: `box-shadow: 4px 4px 0 #000` for a retro/flat look
-- These shadows define edges without implying light source
-
-## Overlap Elements for Layering
-
-- Overlapping one element across a background boundary creates a strong sense of layers
-- Example: a card that straddles a dark hero and a white content area feels layered
-- Example: an avatar that overlaps the edge of a card creates depth without shadows
-
-## Overlapping Images: Invisible Border
-
-- When images overlap each other or a background, edges can clash
-- Add a border that matches the **background color** — an "invisible" border
-- This creates separation between elements without a visible border color
-- Also called a "halo" — a same-color buffer that prevents visual clashing