@maccesar/aiskills 1.16.1 → 1.17.1

package/skills/refactoring-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: refactoring-ui
-description: '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. Inspired by "Refactoring UI" by Adam Wathan & Steve Schoger. Triggers: "how do I make this look better?", color palettes, type scales, spacing systems, visual hierarchy, design reviews, shadows/depth, image handling, empty states, borders.'
+description: 'Design advice grounded in the principles of "Refactoring UI" by Adam Wathan & Steve Schoger. Use this whenever someone is trying to make an interface look better, or asks about visual hierarchy, color palettes and greys, type scales, spacing systems, shadows and depth, images, empty states, borders, dark mode, motion and hover states, or the layout of a modal, form or table — including when they never say "design" and just paste a component asking why it looks off, or say it "feels cramped", "looks generic", "needs polish", "how do I make this look better?". Applies to any stack: Tailwind, plain CSS, React, Blade, mobile. Not for: writing the copy itself, logo or brand identity work, user research, or debugging CSS that renders wrong.'
 ---
 
 # Refactoring UI Skill
@@ -9,26 +9,23 @@ Design advice grounded in the principles taught by Adam Wathan & Steve Schoger i
 
 ## Required workflow (read before responding)
 
-The SKILL.md alone is an **index** of references. The detail you need
-to give accurate answers lives in the reference files. **Reading this
-SKILL.md is not enough.**
+The SKILL.md alone is an **index** of references. The detail you need to give accurate answers lives in the reference files. **Reading this SKILL.md is not enough.**
 
 ### Step 1 — Open the relevant reference files
 
 | Task involves | Required reading |
 |---|---|
-| Color systems, typography, spacing scales — defining the system | [references/01-foundations.md](references/01-foundations.md) |
-| Layout, white space, visual hierarchy, page-level structure | [references/02-page-mechanics.md](references/02-page-mechanics.md) |
-| Color usage, HSL, greys, contrast, shadows, depth, images | [references/03-visual-treatment.md](references/03-visual-treatment.md) |
-| Empty states, borders, accents, finishing touches | [references/04-polish.md](references/04-polish.md) |
-| Motion, microinteractions, transitions, hover/press states, loading | [references/05-motion.md](references/05-motion.md) |
-| Dark mode, multi-theme color tokens, theme toggle, contrast strategy | [references/06-dark-mode.md](references/06-dark-mode.md) |
-| Modals, forms, tables — component-specific layout and behavior patterns | [references/07-component-patterns.md](references/07-component-patterns.md) |
+| Project mindset: feature-first work, scope discipline, defining systems, picking a voice | [references/01-foundations.md](references/01-foundations.md) |
+| Visual hierarchy, layout, white space, spacing scales, typography | [references/02-page-mechanics.md](references/02-page-mechanics.md) |
+| Color systems (HSL, shades, greys, contrast), depth and shadows, image handling | [references/03-visual-treatment.md](references/03-visual-treatment.md) |
+| Empty states, borders, accents, decorative defaults, finishing touches | [references/04-polish.md](references/04-polish.md) |
+| Motion, microinteractions, transitions, hover/press states, loading, `prefers-reduced-motion` — *complementary, not from the book* | [references/05-motion.md](references/05-motion.md) |
+| Dark mode, multi-theme color tokens, theme toggle, contrast strategy — *complementary, extrapolates the book's HSL principles* | [references/06-dark-mode.md](references/06-dark-mode.md) |
+| Modals (focus, layout), forms (labels, validation), tables (density, alignment) — *complementary, extends the book's principles* | [references/07-component-patterns.md](references/07-component-patterns.md) |
 
 ### Step 2 — Output contract
 
-Every design recommendation, ratio, value, or rule you cite MUST be
-backed by a citation in the form:
+Every design recommendation, ratio, value, or rule you cite MUST be backed by a citation in the form:
 
 `[source: references/<file>.md]`
 
@@ -36,43 +33,21 @@ Example: *"Use weight and color, not just font size, to establish hierarchy [sou
 
 ### Step 3 — If you must answer from memory
 
-If you write a claim without having read the reference that backs it,
-prepend `FROM_MEMORY (unverified):` to that claim. Do not hide it.
+If you write a claim without having read the reference that backs it, prepend `FROM_MEMORY (unverified):` to that claim. Do not hide it.
 
 ### Banned behaviors
 
-- ❌ Inventing ratios, scale values, contrast numbers, or rules not in the references
-- ❌ Reproducing the book's prose, illustrations, or examples verbatim — paraphrase only
-- ❌ Mixing in advice from unrelated design systems (Material, HIG, Tailwind defaults) as if it were *Refactoring UI* doctrine
-- ❌ Marking the answer complete without listing which reference files you read
+These four are where advice like this usually goes wrong, so they're worth naming:
 
-## When to use
-
-- User asks "how do I make this look better?"
-- User asks about color palettes, type scales, or spacing systems
-- User asks about visual hierarchy or emphasis
-- User is designing a UI component, page, or layout
-- User wants a design review or critique
-- User asks about shadows, depth, or layering
-- User asks about handling images in UI
-- User asks about empty states, borders, or decorative elements
+- Inventing ratios, scale values, contrast numbers, or rules not in the references. A made-up number is indistinguishable from a real one once it's in someone's stylesheet.
+- Reproducing the book's prose, illustrations, or examples verbatim. The references paraphrase on purpose — the original material belongs to its authors and is worth buying.
+- Presenting advice from unrelated design systems (Material, HIG, Tailwind defaults) as *Refactoring UI* doctrine. Those systems are fine; attributing them here makes the citation meaningless.
+- Marking the answer complete without listing which reference files you read. The list is what lets the reader tell a grounded answer from a plausible one.
 
 ## Source
 
 Inspired by 'Refactoring UI' by Adam Wathan & Steve Schoger — refactoringui.com
 
-## Reference Files
-
-| 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 |
-| `references/05-motion.md`           | Motion system (durations, easings), hover/press states, loading patterns, prefers-reduced-motion — **complementary** (not from RUI) |
-| `references/06-dark-mode.md`        | Dark mode color tokens, text contrast, shadow handling, images, theme toggle — **complementary** (extrapolates RUI's HSL principles) |
-| `references/07-component-patterns.md` | Modals (focus, layout), forms (labels, validation), tables (density, alignment) — **complementary** (extends RUI principles to specific components) |
-
 ## Anti-Patterns to Watch For
 
 - Designing layouts/navs/shells before designing real features [source: references/01-foundations.md]
@@ -84,6 +59,25 @@ Inspired by 'Refactoring UI' by Adam Wathan & Steve Schoger — refactoringui.co
 - Designing with placeholder images instead of real content [source: references/03-visual-treatment.md]
 - Shrinking a logo down to use as a favicon [source: references/03-visual-treatment.md]
 - Using preprocessor `lighten()` / `darken()` to derive shades [source: references/03-visual-treatment.md]
+- Leaving an empty state as a bare "No data" rectangle — it's often the first thing a new user sees [source: references/04-polish.md]
+- Rendering tabs, filters or pagination that have nothing to operate on (reads as broken) [source: references/04-polish.md]
+- Reaching for a border when a shadow, a second background color, or more space separates better [source: references/04-polish.md]
+- Shipping browser-default bullets, checkboxes and radios [source: references/04-polish.md]
+- Animating layout properties (`width`, `top`, `margin`) instead of `transform` / `opacity` [source: references/05-motion.md]
+- Inventing a duration per component instead of picking from a fixed motion scale [source: references/05-motion.md]
+- Scaling a whole element up on hover (1.05×), or animating font size [source: references/05-motion.md]
+- Showing a spinner before ~150ms of waiting [source: references/05-motion.md]
+- Ignoring `prefers-reduced-motion` [source: references/05-motion.md]
+- Pure `#000` for the canvas, or pure white for text [source: references/06-dark-mode.md]
+- Producing dark mode with `filter: invert(1)` [source: references/06-dark-mode.md]
+- Reusing the light-mode brand color in dark mode without rechecking contrast [source: references/06-dark-mode.md]
+- Applying the theme after first paint (flash of the wrong theme on every load) [source: references/06-dark-mode.md]
+- Keeping every light-mode shadow unchanged on a dark canvas, where it's invisible [source: references/06-dark-mode.md]
+- Using a placeholder as the only label [source: references/07-component-patterns.md]
+- Validating a field on every keystroke instead of on blur [source: references/07-component-patterns.md]
+- A modal with no focus trap, or centered vertically instead of anchored near the top [source: references/07-component-patterns.md]
+- Left-aligning numeric columns, which hides magnitude [source: references/07-component-patterns.md]
+- A translucent sticky table header, with rows showing through it [source: references/07-component-patterns.md]
 
 ## Attribution