@skilly-hand/skilly-hand 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,61 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+### Added
+- _None._
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.15.0] - 2026-04-05
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.15.0)
+
+### Added
+
+- **frontend-design skill v1.1.0:** New `design-context-setter` agent for capturing design intent on greenfield projects via a persistent `DESIGN.md` file
+- **frontend-design skill v1.1.0:** New `motion-designer` agent for stack-aware animations and micro-interactions with GPU safety and `prefers-reduced-motion` compliance
+- **frontend-design skill v1.1.0:** New `visual-refiner` agent for post-generation quality evaluation (AI slop detection, interaction state coverage, Nielsen's heuristics, directional refinement)
+- **frontend-design skill v1.1.0:** New `aesthetic-archetypes` reference asset with 8 design archetypes for greenfield project direction
+- Enhanced `component-designer` with aesthetic principles, DESIGN.md integration, and complete interaction-state checklist
+
+### Changed
+
+- Updated `AGENTS.md` with expanded frontend-design workflow triggers and routing
+- Updated frontend-design routing map to include optional motion and visual refinement phases
+- Expanded frontend-design auto-invoke triggers to include greenfield setup, motion, and visual refinement scenarios
+
+### Fixed
+
+- _None._
+
+### Removed
+
+- Removed "Clarification-First Planning Workflow" from `AGENTS.md` (superseded by refined workflows)
+
+## [0.14.0] - 2026-04-06
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.14.0)
+
+### Added
+- _None._
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.13.0] - 2026-04-05
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.13.0)
+
 ### Added
 - Figma plugin detection support
 - New test fixtures for figma-plugin projects
@@ -18,8 +73,6 @@ All notable changes to this project are documented in this file.
 
 ### Removed
 - _None._
-
-## [0.12.0] - 2026-04-05
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.12.0)
 
 ### Added

package/catalog/skills/frontend-design/SKILL.md

@@ -8,10 +8,10 @@ Use this skill when:
 - You are adding new visual elements that must match the project's existing design language.
 - You are refactoring styling or structure of frontend code to align with established patterns.
 - You need to choose between UI components, tokens, or styles already available in the project.
+- You are starting a greenfield project and need to establish a design direction before building.
 
 Do not use this skill for:
 
-- Greenfield design system creation with no existing codebase to read from.
 - Backend, API, or data-layer tasks with no UI surface.
 - Design tool work (Figma, Sketch) unrelated to code implementation.
 - Projects where the user has explicitly opted out of stack detection.
@@ -25,17 +25,40 @@ Always run stack detection first. Never skip to design.
 | Step | Intent | Sub-agent |
 | --- | --- | --- |
 | 0 (always first) | Detect framework, UI library, CSS approach, tokens, and existing patterns | [agents/stack-detector.md](agents/stack-detector.md) |
+| 0b (if no DESIGN.md and no existing components) | Gather design intent and create DESIGN.md | [agents/design-context-setter.md](agents/design-context-setter.md) |
 | 1 (only after confirmation) | Design and implement components using confirmed stack | [agents/component-designer.md](agents/component-designer.md) |
+| 2 (optional) | Add motion and micro-interactions | [agents/motion-designer.md](agents/motion-designer.md) |
+| 3 (optional) | Evaluate quality and refine the output | [agents/visual-refiner.md](agents/visual-refiner.md) |
 
 ---
 
 ## Standard Execution Sequence
 
 1. **Run stack detection** — always start with `stack-detector`, no exceptions.
-2. **Present findings to the user** — surface the detected stack clearly and ask for explicit confirmation.
-3. **If anything is unclear or ambiguous, ask** — do not proceed with partial or uncertain information.
-4. **Scan existing tokens and components** — read what already exists before proposing anything.
-5. **Design with confirmed context only** — hand off to `component-designer` only after step 2 is complete.
+2. **Check for DESIGN.md** — if it exists, read it before any design work. If it does not exist and the project has no existing components to sample, run `design-context-setter` to create it.
+3. **Present findings to the user** — surface the detected stack and any DESIGN.md context clearly, then ask for explicit confirmation.
+4. **If anything is unclear or ambiguous, ask** — do not proceed with partial or uncertain information.
+5. **Scan existing tokens and components** — read what already exists before proposing anything.
+6. **Design with confirmed context only** — hand off to `component-designer` only after steps 2–4 are complete.
+7. **Optionally add motion** — invoke `motion-designer` if the component needs micro-interactions.
+8. **Optionally refine** — invoke `visual-refiner` for a quality pass before handoff.
+
+---
+
+## DESIGN.md — Persistent Design Brief
+
+`DESIGN.md` is a plain Markdown file at the project root that captures the project's design intent: target users, brand personality, aesthetic direction, color strategy, typography intent, spacing philosophy, and motion character.
+
+It is created by `design-context-setter` on greenfield projects and can be updated at any time by the user.
+
+**Every agent in this skill reads `DESIGN.md` if it exists before making aesthetic decisions.** This prevents design drift between sessions.
+
+```bash
+# Check if DESIGN.md exists before starting work
+cat DESIGN.md 2>/dev/null
+```
+
+If `DESIGN.md` exists, surface its contents in the stack confirmation step. If it conflicts with what the stack detector found (e.g., DESIGN.md says "warm neutrals" but all existing tokens are cool blues), surface the conflict and ask the user which to follow.
 
 ---
 
@@ -46,6 +69,7 @@ Always run stack detection first. Never skip to design.
 Before writing a single line of UI code or proposing any design, run [agents/stack-detector.md](agents/stack-detector.md).
 
 This means:
+
 - Reading `package.json` to identify the framework and installed libraries.
 - Detecting CSS approach (Tailwind, CSS Modules, styled-components, Sass, vanilla).
 - Finding existing design tokens (CSS custom properties, theme files, `tokens.json`).
@@ -67,9 +91,10 @@ If the token does not exist in the project, do not invent it. Ask the user: "Thi
 
 ### Pattern 3: Confirm Before Every Design Decision
 
-At every fork — layout choice, component variant, color, interaction pattern — if the right answer is not derivable from the existing code, ask the user.
+At every fork — layout choice, component variant, color, interaction pattern — if the right answer is not derivable from the existing code or from `DESIGN.md`, ask the user.
 
 Examples of things that require confirmation:
+
 - Which existing component to base a new one on.
 - Whether to use Tailwind utility classes or a CSS module.
 - Whether to match a specific existing page's spacing rhythm or start fresh.
@@ -80,12 +105,15 @@ Short, specific questions are better than long ambiguous ones. One question at a
 ### Pattern 4: Follow the Project's Visual Language
 
 After stack detection, read 3–5 existing components before proposing any design. Identify:
+
 - The naming convention (PascalCase components, BEM CSS, camelCase tokens, etc.)
 - The composition pattern (atomic components, compound components, render props, slots)
 - The styling approach (co-located styles, global theme, utility-first classes)
 
 Every new component or style must feel like it was written by the same team that wrote the existing code — not imported from a different design system.
 
+If no existing components are found, use `DESIGN.md` as the visual language reference. If neither exists, run `design-context-setter` before proceeding.
+
 ---
 
 ## What Not To Do
@@ -95,13 +123,14 @@ These are the most critical rules. Violating any of them produces AI slop.
 - **Never assume a UI library is present** without verifying it in `package.json`. Shadcn and Radix look similar in JSX — check the deps.
 - **Never pick colors, fonts, or spacing values not already in the project**. If the project has no purple, do not introduce purple.
 - **Never use Inter as a default font** unless it is explicitly declared in the project. Inter is a sign of uncontextualized AI output.
-- **Never generate a component without reading at least one existing component first**. The project's conventions must be the template.
+- **Never generate a component without reading at least one existing component first** (or DESIGN.md if no components exist). The project's conventions must be the template.
 - **Never apply a generic layout** (hero + cards + CTA, standard nav + footer) without verifying the project already uses or wants that structure.
-- **Never chain design decisions silently**. If one decision implies a downstream choice (e.g. using a grid library implies a layout system), surface it.
+- **Never chain design decisions silently**. If one decision implies a downstream choice (e.g., using a grid library implies a layout system), surface it.
 - **Never proceed after ambiguity**. If the detected stack is inconsistent (e.g., Tailwind and styled-components both present), stop and ask which one is canonical.
 - **Never treat a partial stack detection as complete**. If `package.json` was readable but no component files were found, say so and ask for the component directory.
 - **Never ship a "placeholder" or "you can customize this later" design**. Every value must be intentional and project-derived.
 - **Never skip the confirmation step** even if the stack looks obvious. One confirmation prevents ten corrections.
+- **Never ignore DESIGN.md when it exists**. It represents deliberate decisions the user has already made.
 
 ---
 
@@ -113,11 +142,17 @@ User asks for UI work
        NO  -> Run stack-detector, present findings, ask for confirmation
        YES -> Continue
 
+  -> Does DESIGN.md exist?
+       YES -> Read it; surface any conflicts with detected stack
+       NO  -> Are there existing components to sample?
+                YES -> Sample them (Pattern 4)
+                NO  -> Run design-context-setter to create DESIGN.md
+
 Is the requested component similar to an existing one in the project?
   YES -> Read the existing component, use it as the structural and styling template
   NO  -> Ask the user which existing component is closest, or if this is a net-new pattern
 
-Does the design require a token/value (color, spacing, font) not yet found in the project?
+Does the design require a token/value (color, spacing, font) not yet found in the project or DESIGN.md?
   YES -> Ask the user: add a new token, use an existing one, or clarify?
   NO  -> Use the existing token
 
@@ -135,6 +170,10 @@ Is the CSS approach styled-components or CSS-in-JS?
 
 Ready to implement?
   YES -> Hand off to component-designer with full confirmed context
+
+After generation:
+  -> Does the component need motion? -> Invoke motion-designer
+  -> Does the output need a quality pass? -> Invoke visual-refiner
 ```
 
 ---
@@ -192,6 +231,9 @@ grep '"@radix-ui' package.json
 ## Commands
 
 ```bash
+# Check for DESIGN.md at project root
+cat DESIGN.md 2>/dev/null
+
 # Read project dependencies
 cat package.json | grep -A 50 '"dependencies"'
 
@@ -213,5 +255,9 @@ find src/components -maxdepth 2 -name "*.tsx" -o -name "*.vue" | head -10
 ## Resources
 
 - Stack detection procedure: [agents/stack-detector.md](agents/stack-detector.md)
+- Design context setup (greenfield): [agents/design-context-setter.md](agents/design-context-setter.md)
 - Component design rules: [agents/component-designer.md](agents/component-designer.md)
+- Motion and micro-interactions: [agents/motion-designer.md](agents/motion-designer.md)
+- Visual quality refinement: [agents/visual-refiner.md](agents/visual-refiner.md)
 - Full scan checklist: [assets/stack-scan-checklist.md](assets/stack-scan-checklist.md)
+- Aesthetic archetypes reference: [assets/aesthetic-archetypes.md](assets/aesthetic-archetypes.md)

package/catalog/skills/frontend-design/agents/component-designer.md

@@ -8,6 +8,8 @@ If the user asks you to design something and no confirmed stack summary exists,
 "Before I design anything, I need to scan the project. Running stack detection first."
 Then invoke stack-detector. Do not skip this, even if the task feels small.
 
+**Also read `DESIGN.md` before making any aesthetic decisions.** If it exists at the project root, its aesthetic direction, color strategy, and typography intent govern all choices that are not already constrained by the project's existing tokens or components. If `DESIGN.md` conflicts with detected project tokens, surface the conflict to the user before proceeding.
+
 ---
 
 ## When to Use
@@ -42,23 +44,39 @@ These rules are absolute. No exceptions without explicit user confirmation.
 
 ---
 
+## Aesthetic Principles
+
+These apply within the constraints of the confirmed stack — they guide choices when multiple options are equally valid.
+
+- Prefer generous whitespace over cramped layouts. When in doubt, add more space.
+- Use size and weight to establish hierarchy before reaching for color.
+- One clear visual focus per component — the most important element should be unmistakable.
+- Avoid equal-weight elements. If everything is emphasized, nothing is.
+- When `DESIGN.md` defines a motion character, let it inform transition presence even at this stage — flag it for `motion-designer` rather than omitting it entirely.
+
+---
+
 ## Questioning Protocol
 
 At every point of uncertainty, ask the user a short, specific question before proceeding.
 
 **Layout questions:**
+
 - "Should this component use the same grid as [ExistingPage], or does it have different spacing requirements?"
 - "The project breakpoints in tailwind.config are `sm`, `md`, `lg`. Should this component be responsive at all three, or only `md` and above?"
 
 **Style questions:**
+
 - "I see `--color-primary` and `--color-accent` in globals.css. Which one should this button use for its default state?"
 - "The existing Card uses `rounded-md`. Should this modal also use `rounded-md`, or does it need a sharper or rounder corner?"
 
 **Interaction / state questions:**
+
 - "Should this component have a loading state? I don't see a Skeleton or Spinner imported in other components — should I add one or skip it?"
 - "The existing Input has a `disabled` prop. Should this new Select also handle `disabled`?"
 
 **Composition questions:**
+
 - "Do you want this to accept children (composable) or receive structured props (data-driven)? The existing Card uses both — which pattern fits here?"
 
 One question at a time. Do not front-load a list of 8 questions before starting.
@@ -79,6 +97,11 @@ Before finalizing any output, verify every item:
 - [ ] No new design tokens were invented without explicit user approval.
 - [ ] The component was cross-referenced against at least one existing component for structural consistency.
 - [ ] Accessibility: semantic HTML elements, aria attributes consistent with existing components.
+- [ ] All interactive states handled: hover, focus-visible, active, disabled.
+- [ ] Loading and empty states considered — ask the user if not obvious from the request.
+- [ ] Error state handled where the component can receive or display errors.
+- [ ] If any animation was added, `prefers-reduced-motion` is respected.
+- [ ] `DESIGN.md` was read and its aesthetic direction informed choices where tokens left room for judgment.
 
 ---
 
@@ -89,7 +112,8 @@ A finished component from this agent:
 - Reads like it was written by the existing team.
 - Uses the same imports, utilities, and style tokens as the rest of the codebase.
 - Has no values that can't be traced back to a confirmed project resource.
-- Includes no design decisions that weren't explicitly confirmed by the user or directly derived from existing code.
+- Includes no design decisions that weren't explicitly confirmed by the user or directly derived from existing code or `DESIGN.md`.
 - Has no "you can customize this" placeholder comments.
+- Has all interactive states implemented, not deferred.
 
 If the output doesn't meet this bar, it is not done.

package/catalog/skills/frontend-design/agents/design-context-setter.md

@@ -0,0 +1,156 @@
+# Design Context Setter
+
+## Goal
+
+Gather the project's design intent once, then write it to `DESIGN.md` at the project root. This file becomes the single source of truth for all design decisions across sessions and across agents. Every other agent in this skill reads `DESIGN.md` before making aesthetic choices.
+
+This agent is modeled on how modern AI-first design platforms (Stitch, v0, Galileo) treat a persistent design brief — a short, always-available document that anchors every generation.
+
+---
+
+## When to Use
+
+Run this agent when:
+
+- `DESIGN.md` does not exist at the project root and the project has no existing components to read style conventions from.
+- The user starts a greenfield project (no `src/components`, no existing UI, blank or near-blank codebase).
+- The user says "let's set up the design" or "define the visual direction" before any component work.
+- The stack detector finds no design tokens and no existing components to sample.
+
+Do not run this agent when:
+
+- `DESIGN.md` already exists and the user has not asked to update it. Read it instead.
+- The project has existing components — stack detection provides sufficient context for matching.
+- The user has explicitly said "just match what's there."
+
+---
+
+## Check First
+
+Before starting the interview, check:
+
+```bash
+# Is DESIGN.md already present?
+cat DESIGN.md 2>/dev/null
+
+# Are there existing components to learn from instead?
+find src -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" 2>/dev/null | head -5
+```
+
+If `DESIGN.md` exists, surface it to the user and ask: "A `DESIGN.md` already exists. Should I use it as-is, update it, or start fresh?"
+
+If components exist but no `DESIGN.md`, suggest: "I found existing components. I can either read those to infer style conventions, or we can write a `DESIGN.md` to set a deliberate direction. Which do you prefer?"
+
+---
+
+## Interview Protocol
+
+Ask these questions one at a time. Do not front-load the full list.
+
+**1. Who is this for?**
+"Who are the primary users of this interface? (e.g., technical professionals, general public, enterprise ops teams, consumers aged 25–35)"
+
+**2. What does this product do — in one sentence?**
+"Describe the product's core value proposition in a single sentence."
+
+**3. What's the brand personality?**
+"Pick 3 adjectives that describe how this interface should feel. Examples: sharp, friendly, calm, bold, minimal, playful, authoritative, warm, precise."
+
+**4. Are there any visual references?**
+"Any products, sites, or brands whose aesthetic this should feel close to? (Optional — skip if none.)"
+
+**5. What's the accessibility baseline?**
+"Should we target WCAG 2.2 Level AA (standard), AAA (enhanced), or is there a specific requirement? Default is AA."
+
+**6. Any hard constraints?**
+"Are there colors, fonts, or patterns that must be used or must be avoided? (brand guidelines, corporate requirements, legal restrictions)"
+
+After collecting answers, propose a brief aesthetic direction and ask for confirmation before writing the file.
+
+---
+
+## Output Format
+
+Write the following structure to `DESIGN.md` at the project root. Every field must come from user answers — no invented values.
+
+```markdown
+# DESIGN.md
+
+> This file is the canonical design brief for this project.
+> All AI agents and contributors should read it before making visual decisions.
+> Update it when the design direction changes.
+
+## Product
+
+**What it is:** [one-sentence description]
+**Primary users:** [user description]
+
+## Brand Personality
+
+**Adjectives:** [3 adjectives from user]
+**Visual references:** [references, or "none specified"]
+
+## Aesthetic Direction
+
+[2–4 sentences written in plain language describing the desired look and feel.
+Derived from the adjectives and references above.
+Example: "Clean, high-contrast layouts with generous whitespace. Typography-driven hierarchy — let size and weight do the work before reaching for color. Warm neutrals, not pure grays. Motion should feel intentional and restrained."]
+
+## Color Strategy
+
+> Intent only — not token declarations. Actual color values are determined after stack detection reads the project's existing tokens.
+
+**Approach:** [e.g., "Monochromatic with a single warm accent" / "High contrast, dark-first" / "Muted palette, earthy tones" / "To be defined — read from stack tokens"]
+**Accent color intent:** [e.g., "Call-to-action only" / "Interactive states only" / "Not yet defined"]
+
+## Typography Intent
+
+> Intent only — not font declarations. Actual font families and sizes are determined after stack detection reads the project's existing tokens or dependencies.
+
+**Character:** [e.g., "Geometric sans-serif for clarity" / "Humanist serif for warmth" / "Monospace for technical credibility" / "To be determined from stack"]
+**Scale approach:** [e.g., "Tight utilitarian scale for app UI" / "Dramatic editorial scale for marketing" / "Match existing project scale"]
+
+## Spacing Philosophy
+
+[e.g., "Generous whitespace — let content breathe" / "Dense, information-rich — prioritize data density" / "Match existing project rhythm"]
+
+## Motion Character
+
+[e.g., "Subtle and purposeful — transitions only, no decorative motion" / "Expressive — micro-interactions on every interaction" / "Minimal — respect reduced-motion by default"]
+
+## Accessibility
+
+**Target level:** [WCAG 2.2 AA / AAA / project-specific]
+**Hard constraints:** [any must-have or must-avoid rules from user]
+
+## Notes
+
+[Any other constraints, references, or decisions captured during setup]
+```
+
+---
+
+## After Writing DESIGN.md
+
+Tell the user:
+
+> `DESIGN.md` has been created at the project root. Every design agent in this skill will read it before making visual decisions. You can edit it at any time — it's plain Markdown.
+>
+> Ready to proceed with stack detection and component design.
+
+Then hand off to `stack-detector.md`.
+
+**If the assistant cannot write files** (sandboxed or read-only environment): Tell the user the DESIGN.md content that would have been written, and ask them to create the file manually or paste it into the project. Do not block on the write failure — treat the content as confirmed context for the current session even if the file was not persisted.
+
+---
+
+## Updating DESIGN.md
+
+If the user asks to update the design direction mid-project:
+
+1. Read the current `DESIGN.md`.
+2. Ask which section they want to change.
+3. Make only the requested change — do not rewrite the whole file.
+4. Confirm the update before writing.
+
+Never overwrite the entire file silently.

package/catalog/skills/frontend-design/agents/motion-designer.md

@@ -0,0 +1,184 @@
+# Motion Designer
+
+## Precondition
+
+**Stack detection must be complete before this agent runs.**
+
+Motion must be implemented using the animation primitives already available in the project's stack. Never introduce a new animation library without the user's explicit approval.
+
+---
+
+## When to Use
+
+Use this agent when:
+
+- A component has been generated and the user asks "add animations," "make this feel alive," or "add micro-interactions."
+- You identify that a key interaction is missing feedback (e.g., a button with no active state transition).
+- The user wants to add entrance animations, loading skeletons, or scroll-driven reveals.
+- You need to implement reduced-motion-safe transitions.
+
+Do not use this agent when:
+
+- Stack detection has not been run.
+- The project has zero animation dependencies and no CSS transition usage in existing components — ask the user before adding anything.
+- The user has explicitly said "no animations."
+
+---
+
+## Animation Stack Detection
+
+Before proposing any motion, identify what animation primitives the project already uses.
+
+```bash
+# Check for animation libraries
+grep -E '"framer-motion"|"@motionone/dom"|"gsap"|"animejs"|"motion"' package.json
+
+# Check for CSS transitions in existing components
+grep -rn "transition" src/ --include="*.css" --include="*.scss" --include="*.module.css" | head -10
+
+# Check for @keyframes usage
+grep -rn "@keyframes" src/ --include="*.css" --include="*.scss" | head -5
+
+# Check for Tailwind animation utilities
+grep -n "transition\|duration\|ease\|animate-" src/ --include="*.tsx" --include="*.vue" | head -10
+```
+
+Report what was found:
+
+```
+Animation stack:
+  Library:     [framer-motion v11 | @motionone/dom | GSAP | none detected]
+  CSS approach: [Tailwind transition utilities | CSS custom properties | @keyframes | none]
+  Existing patterns: [fade-in on mount | slide transitions | skeleton loaders | none found]
+```
+
+If no animation primitives are found, ask: "This project has no existing animation setup. Should I use CSS transitions only (no new dependencies), or would you like to add a library? If so, which one?"
+
+---
+
+## Opportunity Assessment
+
+Evaluate the component for four animation opportunities. Before implementing any of them, summarize what you found and confirm with the user: "I identified N animation opportunities. Here's what I'd add — confirm before I make any changes?" All code changes in this agent require user confirmation, even when framed as feedback fixes.
+
+### 1. Missing Feedback
+
+UI actions that complete silently feel broken. Look for:
+
+- Buttons with no active/press state visual change
+- Form submissions with no loading indicator
+- Toggle switches with no transition
+- Tabs or accordion panels that snap without transition
+
+**Fix**: Add a 100–200ms `transition` on `transform`, `opacity`, or `background-color`. Never animate `width`, `height`, `top`, `left`, `margin`, or `padding` — these trigger layout and cause jank.
+
+### 2. Jarring Transitions
+
+Elements that appear/disappear instantly feel glitchy:
+
+- Modals, drawers, tooltips that pop in without entrance
+- Dropdown menus that appear with no transition
+- Route changes with no fade
+
+**Fix**: 200–350ms `opacity` + `transform: translateY(4px)` entrance. Exit should be faster than entrance (150–250ms).
+
+### 3. Unclear Relationships
+
+Motion can communicate hierarchy and causality:
+
+- List items that load simultaneously when staggered would feel more natural
+- A parent collapsing without carrying its children
+- A notification appearing without connecting to its trigger
+
+**Fix**: Stagger delays of 30–60ms between sibling elements. Keep total stagger duration under 400ms for lists of 6+ items.
+
+### 4. Delight Opportunities
+
+Moments where a small motion adds personality without adding noise:
+
+- Success state on form submission
+- Empty state illustrations that have a subtle loop
+- First-load entrance for a hero section
+
+**Fix**: These are always optional and always ask the user first. Never add delight motion without explicit approval.
+
+---
+
+## Timing Reference
+
+| Use Case | Duration | Easing |
+| -------- | -------- | ------ |
+| Button feedback (press, hover) | 100–150ms | ease-out |
+| Tooltip / popover entrance | 150–200ms | ease-out |
+| Dropdown open | 200–250ms | ease-out |
+| Modal / drawer entrance | 250–350ms | cubic-bezier(0.16, 1, 0.3, 1) |
+| Page / route transition | 300–400ms | ease-in-out |
+| Hero entrance (first load) | 500–800ms | cubic-bezier(0.16, 1, 0.3, 1) |
+| Stagger delay between siblings | 30–60ms | — |
+
+Never exceed 800ms for any UI transition. If it needs more than 800ms, it is decorative animation, not UI motion — ask the user.
+
+---
+
+## GPU Safety Rules
+
+**Only animate these properties** — they are GPU-composited and do not trigger layout:
+
+- `transform` (translate, scale, rotate)
+- `opacity`
+- `filter` (use sparingly — can be expensive)
+
+**Never animate** layout-triggering properties:
+
+- `width`, `height`, `max-height`
+- `top`, `left`, `right`, `bottom`
+- `margin`, `padding`
+- `border-width`
+- `font-size`
+
+If you need a height animation (e.g., accordion expand), use `max-height` with caution, or prefer `transform: scaleY()` + `transform-origin: top`.
+
+---
+
+## Reduced Motion — Non-Negotiable
+
+Every animation added by this agent must respect `prefers-reduced-motion`. No exceptions.
+
+**CSS approach:**
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .animated-element {
+    transition: none;
+    animation: none;
+  }
+}
+```
+
+**Tailwind approach:**
+
+```html
+<div class="transition-opacity duration-200 motion-reduce:transition-none">
+```
+
+**Framer Motion approach:**
+
+```tsx
+const shouldReduce = useReducedMotion();
+<motion.div animate={shouldReduce ? {} : { opacity: 1, y: 0 }} />
+```
+
+If the existing project has no `prefers-reduced-motion` handling anywhere, note it and add it to every animation you introduce.
+
+---
+
+## Implementation Checklist
+
+Before finalizing any motion work:
+
+- [ ] All animation primitives are from the confirmed stack — no new dependencies added without approval.
+- [ ] No layout-triggering properties are animated.
+- [ ] All animations have a `prefers-reduced-motion` fallback.
+- [ ] Timing values are within the reference ranges above.
+- [ ] Delight animations were explicitly approved by the user.
+- [ ] No animation duration exceeds 800ms.
+- [ ] Stagger lists cap total duration at 400ms.

package/catalog/skills/frontend-design/agents/visual-refiner.md

@@ -0,0 +1,137 @@
+# Visual Refiner
+
+## Precondition
+
+**Run only after `component-designer` has produced output.**
+
+This agent evaluates what was just generated — not what the user wants next. Its job is to close the quality gap between "technically correct" and "ready to ship."
+
+---
+
+## When to Use
+
+Use this agent when:
+
+- A component or page has been generated and needs a quality check before the user moves on.
+- The user asks "does this look right?", "can you improve this?", or "polish this."
+- The generated output feels generic or inconsistent — even if it technically matches the stack.
+- You want to verify all interactive states are handled before handoff.
+
+Do not use this agent when:
+
+- Stack detection has not yet been run.
+- No component has been generated in this session yet.
+- The user has explicitly said "it's fine as-is."
+
+---
+
+## Evaluation Protocol
+
+Run all four checks. Do not skip any. Report findings grouped by check — do not interleave.
+
+---
+
+### Check 1 — AI Slop Detection
+
+Look for generic patterns that signal uncontextualized AI output. Flag each one found.
+
+**Visual tells to catch:**
+
+- Glassmorphism (backdrop-filter: blur + semi-transparent backgrounds with no established project precedent)
+- Default Inter font with no project declaration
+- Standard hero + cards + CTA layout with no project-specific rationale
+- Pure `#000000` or `#ffffff` for text/backgrounds instead of project tokens
+- Generic card shadows (`box-shadow: 0 2px 8px rgba(0,0,0,0.1)`) not derived from project tokens
+- Gradient text (`background-clip: text`) used decoratively without project precedent
+- Icon + title + description card grids as default empty-state filler
+- Identical padding and border-radius across every element (uniform blandness)
+
+For each flag: name the pattern, show the line, and suggest a project-derived alternative.
+
+---
+
+### Check 2 — Interaction State Coverage
+
+Verify every interactive element has all required states. Missing states are incomplete work, not optional polish.
+
+**Required states per element type:**
+
+| Element | Required States |
+| ------- | --------------- |
+| Button (primary) | default, hover, focus-visible, active, disabled, loading |
+| Button (secondary/ghost) | default, hover, focus-visible, active, disabled |
+| Input / Textarea | default, focus, filled, error, disabled |
+| Select / Dropdown | default, open, selected, disabled |
+| Link | default, hover, visited, focus-visible |
+| Checkbox / Radio | unchecked, checked, indeterminate (checkbox), focus, disabled |
+| Toggle / Switch | on, off, focus, disabled |
+| Card (interactive) | default, hover, focus, selected |
+
+For each missing state: name the element, name the missing state, and provide the implementation using confirmed project tokens.
+
+---
+
+### Check 3 — Nielsen's Heuristics (abbreviated)
+
+Score only the heuristics relevant to a component-level review. Skip system-level heuristics.
+
+| Heuristic | Check |
+| --------- | ----- |
+| Visibility of system status | Does loading/processing state communicate progress? |
+| Match between system and world | Do labels use plain language the user would recognize? |
+| Error prevention | Does the component validate or guard against bad input? |
+| Recognition over recall | Are actions visible, not hidden behind hover/guess? |
+| Consistency and standards | Does this match patterns established elsewhere in the project? |
+| Aesthetic and minimalist design | Is every element present earning its space? |
+
+Rate each: **Pass**, **Minor issue**, or **Blocker**. Provide a one-line note for anything not Pass.
+
+---
+
+### Check 4 — Directional Assessment
+
+After the three checks above, ask the user to choose a direction:
+
+> The component is functionally solid. Here are three directions to take the refinement:
+>
+> **A — Polish**: Fix the flagged issues and fill missing states. No visual changes beyond corrections.
+>
+> **B — Bolder**: Increase visual impact. Larger type jumps, stronger contrast, more distinctive spacing rhythm. Still uses project tokens.
+>
+> **C — Quieter**: Reduce visual weight. More whitespace, softer contrast, subtler hierarchy. Still uses project tokens.
+>
+> Which direction, or a combination? (Or say "done" to accept as-is.)
+
+Do not apply any directional changes without the user's explicit choice. Fixes from Check 1–3 are always applied.
+
+---
+
+## Refinement Rules
+
+When applying any refinement:
+
+1. Use only tokens confirmed by stack detection or declared in `DESIGN.md`.
+2. Do not introduce new dependencies.
+3. Do not change the component's public API (props, events, slots) unless the user asks.
+4. Do not add animation in this agent — hand off to `motion-designer` for that.
+5. One round of refinement per invocation. If the user wants another pass, re-invoke this agent.
+
+---
+
+## Output Format
+
+```text
+VISUAL REFINER REPORT
+---------------------
+AI Slop Check:    [N flags found / Clean]
+State Coverage:   [N states missing / Complete]
+Heuristics:       [N issues / All pass]
+
+FINDINGS:
+[grouped list of findings with suggested fixes]
+
+RECOMMENDED ACTION:
+[Polish only / Polish + Direction A/B/C / No changes needed]
+```
+
+After applying fixes, summarize what changed in 2–3 bullet points. Do not narrate every line edited.

package/catalog/skills/frontend-design/assets/aesthetic-archetypes.md

@@ -0,0 +1,155 @@
+# Aesthetic Archetypes
+
+Reference card for greenfield projects or when a user asks for design direction with no existing codebase to read from.
+
+Each archetype describes a coherent visual personality using framework-agnostic, implementation-neutral language. No library names, no specific color values, no font names — those are determined by the project's actual stack after the archetype is chosen.
+
+**How to use:**
+
+1. Present 2–3 options that best match the user's brand personality adjectives from `DESIGN.md`.
+2. Let the user choose or mix.
+3. Translate their choice into stack-specific tokens only after the stack is confirmed.
+
+---
+
+## 1. Refined Minimal
+
+**Character**: Quiet confidence. Less is deliberate, not lazy.
+
+**Typography**: Small, tight type scale. Generous leading. Weight does the work — one bold statement surrounded by light body. No more than two font roles.
+
+**Color**: Near-monochromatic. One neutral family (warm or cool), one restrained accent used sparingly. Near-black text, near-white backgrounds, or their dark-mode inversion.
+
+**Spacing**: Generous. Breathing room is the dominant visual element. Consistent, predictable rhythm.
+
+**Motion**: Subtle. Fade and micro-translate on interaction. Nothing draws attention to itself.
+
+**Avoid**: Decorative dividers, rounded corners exceeding the system's established radius, anything that shouts.
+
+---
+
+## 2. Editorial
+
+**Character**: Print-informed. Content is the design.
+
+**Typography**: Dramatic scale jumps. Display-size headings, small caption text. Mix of weights within a single family, or intentional contrast between a display and body face.
+
+**Color**: High contrast. Often near-black + near-white + one ink-like accent. Color is used to mark, not decorate.
+
+**Spacing**: Asymmetric. Grid-breaking is intentional. Vertical rhythm anchors the layout.
+
+**Motion**: Minimal — content should feel immediate. Scroll-driven reveals acceptable.
+
+**Avoid**: Card-heavy layouts, rounded blobs, friendly pastels.
+
+---
+
+## 3. Brutalist
+
+**Character**: Uncompromising. Honesty over comfort.
+
+**Typography**: System stack or intentionally unglamorous. Oversized. Unkerned when intentional. All-caps statements.
+
+**Color**: High contrast. Black, white, and one harsh accent (or pure black and white only). No gradients.
+
+**Spacing**: Structural — not generous, not cramped. Grid is exposed.
+
+**Motion**: Instant or near-instant. Snap, not glide.
+
+**Avoid**: Soft shadows, border-radius, anything "friendly."
+
+---
+
+## 4. Retro-Futuristic
+
+**Character**: Technology filtered through nostalgia.
+
+**Typography**: Geometric or monospace. Tight tracking. All-caps labels. Clear grid hierarchy.
+
+**Color**: Deep backgrounds (near-black or dark navy), bright accent (neon-adjacent — high chroma, not true neon). Subtle scanline or grid texture acceptable.
+
+**Spacing**: Dense with breathing room only at macro level. Sections feel packed but orderly.
+
+**Motion**: Purposeful. Reveal effects, typewriter entrances, scan-line wipes. All must have reduced-motion fallbacks.
+
+**Avoid**: Glassmorphism, light-mode defaults, organic shapes.
+
+---
+
+## 5. Organic
+
+**Character**: Human-made, unhurried.
+
+**Typography**: Humanist or transitional — faces with visible calligraphic origin. Variable weight welcomed. Generous leading.
+
+**Color**: Earth-adjacent. Warm neutrals, muted greens, terracotta, dusty indigo. Nothing fully saturated.
+
+**Spacing**: Flowing. Sections breathe into each other. Asymmetry that feels natural, not forced.
+
+**Motion**: Eases that feel physical — spring or custom cubic-bezier that overshoots slightly. Gentle.
+
+**Avoid**: Sharp corners, high-tech palettes, monospace.
+
+---
+
+## 6. Luxury
+
+**Character**: Restraint signals value.
+
+**Typography**: Elegant — thin weights, generous tracking on headings. Serif display for brand moments, clean sans for utility.
+
+**Color**: Muted, sophisticated. Champagne, slate, obsidian, aged gold. Saturation deliberately low. One metallic or warm-neutral accent.
+
+**Spacing**: Very generous. White space is a premium material.
+
+**Motion**: Slow and deliberate. 400–600ms entrances. Ease-out only — nothing bounces.
+
+**Avoid**: Bright colors, heavy weights, any pattern that reads as cheap or casual.
+
+---
+
+## 7. Playful
+
+**Character**: Fun is a feature, not a compromise.
+
+**Typography**: Rounded or friendly. Variable weight for expression. Larger scale than strictly necessary.
+
+**Color**: Multi-hue. 3–4 colors with clear semantic roles. Saturated but not harsh — use perceptual uniformity to keep brightness balanced.
+
+**Spacing**: Responsive to content, not rigid. Cards can be different sizes. Grid can breathe unevenly.
+
+**Motion**: Expressive micro-interactions. Confirmation states feel satisfying. Always reduced-motion safe.
+
+**Avoid**: Pure black text, sharp corners, anything that reads as corporate or cold.
+
+---
+
+## 8. Industrial
+
+**Character**: Form follows function. No apology for complexity.
+
+**Typography**: Utilitarian sans-serif. Dense but readable. Tabular figures for data. Weight for hierarchy, not decoration.
+
+**Color**: Neutral-forward. Grays, steel, occasionally safety-signal accent (amber, red) for state only. Not decorative.
+
+**Spacing**: Dense. Information-rich layouts. Tables, grids, dashboards. Whitespace is used to separate data, not to decorate.
+
+**Motion**: Minimal. State changes are instant or near-instant. Loading indicators, not entrances.
+
+**Avoid**: Rounded blobs, decorative gradients, anything that prioritizes aesthetics over clarity.
+
+---
+
+## Mixing Archetypes
+
+Users often want combinations. Common pairings:
+
+| Combination | Character |
+| ----------- | --------- |
+| Refined Minimal + Editorial | High-end content publishing |
+| Industrial + Retro-Futuristic | Developer tools with personality |
+| Organic + Luxury | Premium wellness or lifestyle |
+| Playful + Refined Minimal | Consumer product with restraint |
+| Brutalist + Editorial | Independent media, strong POV |
+
+When mixing, one archetype leads (governs spacing and color) and the other accents (contributes a single element — e.g., typography from Editorial onto a Refined Minimal base).

package/catalog/skills/frontend-design/manifest.json

@@ -1,27 +1,31 @@
 {
   "id": "frontend-design",
   "title": "Frontend Design",
-  "description": "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work.",
+  "description": "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, and includes post-generation motion and visual refinement phases.",
   "portable": true,
-  "tags": ["frontend", "design", "workflow", "ui"],
+  "tags": ["frontend", "design", "workflow", "ui", "motion", "greenfield"],
   "detectors": ["always"],
   "detectionTriggers": ["manual"],
   "installsFor": ["all"],
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-04",
+    "last-edit": "2026-04-05",
     "license": "Apache-2.0",
-    "version": "1.0.0",
-    "changelog": "Initial frontend-design skill; enforces stack-detection-first workflow before any UI component generation; affects catalog skill coverage for frontend and design workflows",
-    "auto-invoke": "Designing or generating UI components, pages, or layouts in a web or mobile project",
+    "version": "1.1.0",
+    "changelog": "v1.1.0: Added design-context-setter agent for greenfield/DESIGN.md workflow; added visual-refiner agent for post-generation quality evaluation; added motion-designer agent for stack-aware micro-interactions; added aesthetic-archetypes reference asset; expanded SKILL.md routing map with optional motion and refinement phases; upgraded component-designer with interaction states checklist and aesthetic principles",
+    "auto-invoke": "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; adding motion or micro-interactions to existing UI; refining or polishing generated UI output",
     "allowed-tools": ["Read", "Grep", "Glob", "Bash", "Edit", "Write"]
   },
   "files": [
     { "path": "SKILL.md", "kind": "instruction" },
     { "path": "agents/stack-detector.md", "kind": "asset" },
+    { "path": "agents/design-context-setter.md", "kind": "asset" },
     { "path": "agents/component-designer.md", "kind": "asset" },
-    { "path": "assets/stack-scan-checklist.md", "kind": "asset" }
+    { "path": "agents/motion-designer.md", "kind": "asset" },
+    { "path": "agents/visual-refiner.md", "kind": "asset" },
+    { "path": "assets/stack-scan-checklist.md", "kind": "asset" },
+    { "path": "assets/aesthetic-archetypes.md", "kind": "asset" }
   ],
   "dependencies": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {
@@ -31,10 +31,12 @@
     "test": "node --test tests/*.test.js",
     "security:check": "node ./scripts/security-check.mjs",
     "verify:packlist": "node ./scripts/verify-packlist.mjs",
-    "verify:publish": "npm run security:check && npm run catalog:check && npm test && npm run verify:packlist",
+    "verify:versions": "node ./scripts/verify-versions.mjs",
+    "verify:publish": "npm run verify:versions && npm run security:check && npm run catalog:check && npm test && npm run verify:packlist",
     "publish:prepare": "npm run verify:publish && npm pack --dry-run --json",
     "publish:otp": "node ./scripts/publish-with-otp.mjs",
     "publish:next": "node ./scripts/publish-with-otp.mjs --tag next",
+    "setup:hooks": "node ./scripts/setup-hooks.mjs",
     "prepublishOnly": "npm run verify:publish",
     "version": "node ./scripts/release-changelog.mjs",
     "changelog:release": "node ./scripts/release-changelog.mjs",

package/packages/catalog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/catalog",
-  "version": "0.1.0",
+  "version": "0.15.0",
   "private": true,
   "type": "module"
 }

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/cli",
-  "version": "0.1.0",
+  "version": "0.15.0",
   "private": true,
   "type": "module",
   "bin": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.1.0",
+  "version": "0.15.0",
   "private": true,
   "type": "module"
 }

package/packages/detectors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/detectors",
-  "version": "0.1.0",
+  "version": "0.15.0",
   "private": true,
   "type": "module"
 }