@skilly-hand/skilly-hand 0.26.3 → 0.26.4

package/CHANGELOG.md

@@ -16,6 +16,21 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.26.4] - 2026-05-09
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.26.4)
+
+### Added
+- Added taste-reference extraction guidance to `frontend-design`, with Refero Styles and Impeccable-inspired workflows for turning references into register, visual ingredients, anti-references, and DESIGN.md-ready taste contracts.
+
+### Changed
+- Updated `frontend-design` setup, component design, critique, and refinement routing to apply reference-derived taste rules instead of treating visual direction as vague mood language.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.26.3] - 2026-05-09
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.26.3)
 

package/catalog/README.md

@@ -8,7 +8,7 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `agents-root-orchestrator` | Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | core, workflow, orchestration | all |
 | `angular-guidelines` | Guide Angular code generation, review, and performance tuning using latest stable Angular verification, official Angular skill guidance, and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing Angular code artifacts in Angular projects. | angular, frontend, workflow, best-practices | all |
 | `figma-mcp-0to1` | Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns. | figma, mcp, workflow, design | all |
-| `frontend-design` | 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, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish. | frontend, design, workflow, ui, motion, greenfield | all |
+| `frontend-design` | 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, taste-reference extraction, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish. | frontend, design, workflow, ui, motion, greenfield | all |
 | `gsap-animation` | Guide GSAP animation implementation using only official GSAP documentation and the official greensock/gsap-skills source material. Trigger: implementing, reviewing, or choosing GSAP for frontend motion, timelines, ScrollTrigger, React useGSAP, JavaScript animation libraries, or advanced UI animation. | frontend, animation, motion, gsap, workflow | all |
 | `motion-animation` | Guide Motion, formerly Framer Motion, animation implementation using only official Motion documentation. Trigger: implementing, reviewing, or choosing Motion for JavaScript animation, React motion components, gestures, scroll animation, layout animation, exit animation, or framework-agnostic UI motion. | frontend, animation, motion, framer-motion, workflow | all |
 | `output-optimizer` | Optimize output token consumption through compact interpreter modes with controlled expansion when complexity, ambiguity, or risk requires more detail. Trigger: minimizing response verbosity while preserving clarity and correctness. | core, workflow, efficiency, communication | all |

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

@@ -1,12 +1,12 @@
 ---
 name: "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. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish."
+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, taste-reference extraction, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-05-03"
+  last-edit: "2026-05-09"
   license: "Apache-2.0"
-  version: "1.4.0"
-  changelog: "Added Motion-aware routing through motion-animation alongside gsap-animation; improves animation handoffs for Motion-native JavaScript and React projects; affects frontend-design motion sequencing, metadata, and catalog dependencies"
+  version: "1.5.0"
+  changelog: "Added taste-reference extraction guidance sourced from Refero Styles and Impeccable; improves how agents translate visual references, anti-references, and register into DESIGN.md-ready language; affects greenfield design setup, critique, refinement, and resource routing"
   auto-invoke: "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; critiquing generated UI for AI slop; adding motion or micro-interactions to existing UI; refining or polishing generated UI output"
   allowed-tools:
     - "Read"
@@ -59,11 +59,12 @@ Always run stack detection first. Never skip to design.
 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. **Critique after generation** — invoke `critique` for a frontend-only challenge pass before polish.
-8. **Refine from critique** — invoke `visual-refiner` for visual fixes routed by critique.
-9. **Optionally add motion** — invoke `motion-designer` if critique, refinement, or the user identifies a motion need. Route Motion-native JavaScript/React animation through `motion-animation`; route GSAP timelines, ScrollTrigger, and plugin decisions through `gsap-animation`.
+5. **Extract taste from references** — when the user provides visual references or asks for stronger taste, use [assets/taste-reference-extraction.md](assets/taste-reference-extraction.md) to translate examples into concrete design language, anti-references, and register.
+6. **Scan existing tokens and components** — read what already exists before proposing anything.
+7. **Design with confirmed context only** — hand off to `component-designer` only after steps 2–5 are complete.
+8. **Critique after generation** — invoke `critique` for a frontend-only challenge pass before polish.
+9. **Refine from critique** — invoke `visual-refiner` for visual fixes routed by critique.
+10. **Optionally add motion** — invoke `motion-designer` if critique, refinement, or the user identifies a motion need. Route Motion-native JavaScript/React animation through `motion-animation`; route GSAP timelines, ScrollTrigger, and plugin decisions through `gsap-animation`.
 
 ---
 
@@ -136,6 +137,17 @@ Every new component or style must feel like it was written by the same team that
 
 If no existing components are found, use `DESIGN.md` as the visual language reference. If neither exists, run `design-context-setter` before proceeding.
 
+### Pattern 5: Explain Taste as Observable Decisions
+
+When the user provides references, do not summarize them as vibes. Convert each reference into visible, buildable decisions:
+
+- **Register:** brand surface where design is the product, or product surface where design serves repeated use.
+- **Visual ingredients:** type contrast, color role, spacing rhythm, density, radius, elevation, imagery, component shape, and motion character.
+- **Taste rules:** what to repeat, what to avoid, and what would make the design feel off-brand.
+- **Anti-references:** common AI reflexes the project should reject.
+
+Use [assets/taste-reference-extraction.md](assets/taste-reference-extraction.md) for the extraction workflow. Its source model combines Refero Styles' reference-search framing with Impeccable's design vocabulary, register split, and anti-slop detection.
+
 ---
 
 ## What Not To Do
@@ -290,3 +302,4 @@ find src/components -maxdepth 2 -name "*.tsx" -o -name "*.vue" | head -10
 - Motion and micro-interactions: [agents/motion-designer.md](agents/motion-designer.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)
+- Taste reference extraction: [assets/taste-reference-extraction.md](assets/taste-reference-extraction.md)

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

@@ -53,6 +53,7 @@ These apply within the constraints of the confirmed stack — they guide choices
 - 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.
+- If `DESIGN.md` includes visual references or anti-references, translate them through [../assets/taste-reference-extraction.md](../assets/taste-reference-extraction.md): borrow observable decisions, not full layouts.
 
 ---
 

package/catalog/skills/frontend-design/agents/critique.md

@@ -12,6 +12,7 @@ Before critiquing:
 2. Read `DESIGN.md` if it exists.
 3. Inspect the generated/proposed UI source and, when available, the rendered page.
 4. Compare against sampled project components, tokens, and interaction patterns.
+5. If `DESIGN.md` includes references or anti-references, evaluate against the taste rules from [../assets/taste-reference-extraction.md](../assets/taste-reference-extraction.md), not just generic taste.
 
 Do not use this agent when:
 
@@ -65,6 +66,8 @@ Check whether the UI serves the actual product context.
 - Brand: Does it follow `DESIGN.md` personality and anti-references?
 - Mode: Is this a brand surface where design is the product, or a product surface where design serves repeated use?
 - Distinction: Would this still be recognizable if the logo and copy were removed?
+- Reference translation: Did the UI borrow concrete ingredients from the references, or did it imitate a superficial mood?
+- Anti-reference compliance: Did any explicitly rejected pattern slip back in?
 
 ### Pass 3 - Nielsen Heuristics
 

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

@@ -6,6 +6,8 @@ Gather the project's design intent once, then write it to `DESIGN.md` at the pro
 
 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 the user provides references, use the extraction workflow in [../assets/taste-reference-extraction.md](../assets/taste-reference-extraction.md) before drafting the aesthetic direction. It converts reference sites, brands, moods, and anti-references into concrete language the rest of the skill can apply.
+
 ---
 
 ## When to Use
@@ -59,10 +61,20 @@ Ask these questions one at a time. Do not front-load the full list.
 **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?**
+If the user provides references, extract them into:
+
+- what to borrow;
+- what to avoid;
+- whether the target is brand or product register;
+- the visible ingredients that define the taste.
+
+**5. Any anti-references?**
+"Are there products, sites, or AI-looking patterns this should explicitly avoid? Examples: purple gradients, glassmorphism, nested cards, generic centered hero layouts."
+
+**6. 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?**
+**7. 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.
@@ -89,6 +101,7 @@ Write the following structure to `DESIGN.md` at the project root. Every field mu
 
 **Adjectives:** [3 adjectives from user]
 **Visual references:** [references, or "none specified"]
+**Anti-references:** [visual patterns or references to avoid, or "none specified"]
 
 ## Aesthetic Direction
 

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

@@ -35,6 +35,8 @@ Run all four checks. Do not skip any. Report findings grouped by check — do no
 
 Look for generic patterns that signal uncontextualized AI output. Flag each one found.
 
+If `DESIGN.md` includes visual references or anti-references, run the reference taste check in [../assets/taste-reference-extraction.md](../assets/taste-reference-extraction.md) first. A design can be clean and still fail if it ignores the intended register, borrows the wrong ingredient from a reference, or drifts into an explicit anti-reference.
+
 **Visual tells to catch:**
 
 - Glassmorphism (backdrop-filter: blur + semi-transparent backgrounds with no established project precedent)
@@ -45,6 +47,8 @@ Look for generic patterns that signal uncontextualized AI output. Flag each one
 - 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)
+- Product UI treated like a marketing page, or brand/landing work flattened into utilitarian dashboard language
+- Reference mimicry that copies a layout while missing its real taste ingredients
 
 For each flag: name the pattern, show the line, and suggest a project-derived alternative.
 

package/catalog/skills/frontend-design/assets/taste-reference-extraction.md

@@ -0,0 +1,161 @@
+# Taste Reference Extraction
+
+Use this when a user provides visual references, asks for better taste, or wants the agent to explain a design direction in language another AI can reliably apply.
+
+This workflow is informed by two public reference systems:
+
+- Refero Styles: https://styles.refero.design/
+- Impeccable: https://impeccable.style/
+
+Refero's useful pattern is searchable real-product reference extraction: brand, mood, color, typography, URL, spacing, components, and DESIGN.md-ready output. Impeccable's useful pattern is shared design vocabulary: product-vs-brand register, anti-references, command-like refinement dimensions, and deterministic anti-slop checks.
+
+Do not copy either source's site language into project briefs. Use them as a model for how to structure taste into observable decisions.
+
+---
+
+## When to Use
+
+Use this asset when:
+
+- The user names sites, products, brands, moods, or URLs as references.
+- `DESIGN.md` needs stronger language than vague adjectives.
+- A generated UI feels generic but the fix is not obvious from tokens alone.
+- The user asks to make something feel more premium, editorial, playful, precise, calm, technical, or distinctive.
+
+Do not use it to override existing project tokens, accessibility requirements, or explicit user constraints.
+
+---
+
+## Extraction Ladder
+
+Move from vague taste to buildable decisions in this order.
+
+### 1. Register
+
+Classify the surface before choosing visual moves.
+
+| Register | Design Role | Good Taste Looks Like |
+| --- | --- | --- |
+| Brand | Design is the product: landing pages, launches, portfolios, editorial, venues, campaigns | Distinctive imagery, stronger type voice, memorable composition, carefully chosen drama |
+| Product | Design serves repeated work: dashboards, tools, CRM, admin, commerce flows | Fast scanning, durable hierarchy, predictable controls, restrained styling, task-first density |
+| Hybrid | Brand expression wraps a functional flow: onboarding, pricing, checkout, product-led homepage | Brand moments at entry points; product clarity at decision and action points |
+
+Write the register into `DESIGN.md` when it is known.
+
+### 2. Reference Inventory
+
+For each reference, extract the visible ingredients:
+
+```text
+Reference:
+Role: close model / partial ingredient / anti-reference
+Register: brand / product / hybrid
+Borrow:
+- Typography:
+- Color:
+- Spacing and density:
+- Layout structure:
+- Component shape:
+- Imagery or texture:
+- Motion:
+Avoid:
+- Surface-level mimicry:
+- Patterns that would not fit this product:
+```
+
+If the user provides only a mood, ask for one concrete reference or translate the mood into likely ingredients and mark them as assumptions.
+
+### 3. Taste Rules
+
+Convert references into rules the implementation can check.
+
+Good taste rules are concrete:
+
+- "Use color as state and emphasis, not as section decoration."
+- "Favor one strong typographic contrast over multiple decorative containers."
+- "Keep dashboard panels dense and flat; reserve depth for dialogs and active overlays."
+- "Use asymmetry in hero composition, but keep form controls conventional."
+
+Weak taste rules are vague:
+
+- "Make it premium."
+- "Use modern design."
+- "Make it clean."
+- "Add personality."
+
+### 4. Anti-References
+
+Name what must not happen. Anti-references prevent the model from falling back to common AI reflexes.
+
+Capture:
+
+- explicit sites or products to avoid;
+- visual tropes to reject;
+- category cliches to resist;
+- font, palette, layout, or motion reflexes that would make the output generic.
+
+Common anti-reference language:
+
+- no purple-to-blue gradients unless already in the brand system;
+- no glass cards, glow borders, or blurred background blobs as decoration;
+- no nested card stacks for page sections;
+- no icon-tile feature grid as the default explanation pattern;
+- no centered hero plus metrics unless the product actually needs that story;
+- no monospace as shorthand for technical credibility;
+- no motion that does not communicate state, cause, or hierarchy.
+
+### 5. Taste Contract
+
+End with a short contract that can be pasted into `DESIGN.md` or a task prompt.
+
+```markdown
+## Taste Contract
+
+**Register:** [brand/product/hybrid]
+**Reference role:** [what each reference contributes]
+**Borrow:** [3-5 concrete ingredients]
+**Avoid:** [3-5 anti-references]
+**Hierarchy:** [how attention should move]
+**Density:** [sparse, balanced, dense, or context-specific]
+**Color role:** [brand, state, emphasis, data, or restraint]
+**Typography role:** [voice, clarity, editorial contrast, utility]
+**Motion role:** [none, state feedback, spatial continuity, delight]
+**Failure mode:** [what would make this feel generic or wrong]
+```
+
+---
+
+## Reference Use Rules
+
+- Borrow decisions, not whole layouts.
+- Prefer real product evidence over mood words.
+- Keep brand and product registers separate; do not critique one by the other.
+- When references conflict, decide which ingredient each one owns.
+- Let anti-references constrain reflexes before choosing new decoration.
+- Translate every aesthetic claim into at least one implementation lever: type, color, spacing, density, shape, imagery, motion, or copy voice.
+- Do not introduce new tokens without stack confirmation and user approval.
+
+---
+
+## Example
+
+```text
+User says: "Make it feel like Linear and Apple, but not another dark SaaS dashboard."
+
+Register: product
+Reference roles:
+- Linear: density, command-center clarity, restrained dark surfaces
+- Apple: precision, generous detail spacing, high trust, fewer competing borders
+Borrow:
+- crisp text hierarchy with clear primary action
+- muted surfaces with state-driven accent color
+- shallow depth and precise separators instead of card stacks
+- dense tables, but roomy detail panes
+Avoid:
+- neon-on-dark glow effects
+- purple gradients
+- giant centered hero metrics
+- generic rounded cards around every group
+Failure mode:
+- looking like a launch page instead of a work surface
+```

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

@@ -1,7 +1,7 @@
 {
   "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. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish.",
+  "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, taste-reference extraction, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish.",
   "portable": true,
   "tags": ["frontend", "design", "workflow", "ui", "motion", "greenfield"],
   "detectors": ["always"],
@@ -10,10 +10,10 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-05-03",
+    "last-edit": "2026-05-09",
     "license": "Apache-2.0",
-    "version": "1.4.0",
-    "changelog": "Added Motion-aware routing through motion-animation alongside gsap-animation; improves animation handoffs for Motion-native JavaScript and React projects; affects frontend-design motion sequencing, metadata, and catalog dependencies",
+    "version": "1.5.0",
+    "changelog": "Added taste-reference extraction guidance sourced from Refero Styles and Impeccable; improves how agents translate visual references, anti-references, and register into DESIGN.md-ready language; affects greenfield design setup, critique, refinement, and resource routing",
     "auto-invoke": "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; critiquing generated UI for AI slop; adding motion or micro-interactions to existing UI; refining or polishing generated UI output",
     "allowed-modes": [
       "stack-detector",
@@ -34,7 +34,8 @@
     { "path": "agents/visual-refiner.md", "kind": "asset" },
     { "path": "agents/motion-designer.md", "kind": "asset" },
     { "path": "assets/stack-scan-checklist.md", "kind": "asset" },
-    { "path": "assets/aesthetic-archetypes.md", "kind": "asset" }
+    { "path": "assets/aesthetic-archetypes.md", "kind": "asset" },
+    { "path": "assets/taste-reference-extraction.md", "kind": "asset" }
   ],
   "dependencies": ["motion-animation", "gsap-animation"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.26.3",
+  "version": "0.26.4",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "repository": {

package/packages/catalog/package.json

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

package/packages/cli/package.json

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

package/packages/core/package.json

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

package/packages/detectors/package.json

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