From f683f413c81e5a1adc58593897837bf3ad7af2b7 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Mon, 30 Mar 2026 14:04:54 -0700 Subject: [PATCH] Rename frontend-design to impeccable, fold teach-impeccable into teach mode Major skill consolidation for v2.0: - Rename source/skills/frontend-design/ to source/skills/impeccable/ with user-invocable: true and argument-hint: "[teach]" - Fold teach-impeccable body into impeccable as "Teach Mode" section, activated via /impeccable teach - Create deprecation shims: - frontend-design: redirects to /impeccable - teach-impeccable: redirects to /impeccable teach - Update all 16 skill cross-references from {{command_prefix}}frontend-design to {{command_prefix}}impeccable and {{command_prefix}}teach-impeccable to {{command_prefix}}impeccable teach - Update CLI sentinel detection to use 'impeccable' (with teach-impeccable as legacy fallback) - Update build system readPatterns() path and EXCLUDED_FROM_SUGGESTIONS - Update all public files (data.js, cheatsheet, index, viz, demos) - Update all documentation (README, NOTICE, AGENTS, plugin.json) - Update all test expectations Co-Authored-By: Claude Opus 4.6 (1M context) --- .agents/skills/adapt/SKILL.md | 2 +- .agents/skills/animate/SKILL.md | 2 +- .agents/skills/arrange/SKILL.md | 4 +- .agents/skills/audit/SKILL.md | 4 +- .agents/skills/bolder/SKILL.md | 6 +- .agents/skills/clarify/SKILL.md | 2 +- .agents/skills/colorize/SKILL.md | 2 +- .agents/skills/critique/SKILL.md | 6 +- .agents/skills/critique/reference/personas.md | 2 +- .agents/skills/delight/SKILL.md | 2 +- .agents/skills/distill/SKILL.md | 2 +- .agents/skills/frontend-design/SKILL.md | 147 +----------- .agents/skills/impeccable/SKILL.md | 219 ++++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 .agents/skills/normalize/SKILL.md | 2 +- .agents/skills/onboard/SKILL.md | 2 +- .agents/skills/overdrive/SKILL.md | 2 +- .agents/skills/polish/SKILL.md | 2 +- .agents/skills/quieter/SKILL.md | 2 +- .agents/skills/teach-impeccable/SKILL.md | 68 +----- .agents/skills/typeset/SKILL.md | 4 +- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- .claude/skills/adapt/SKILL.md | 2 +- .claude/skills/animate/SKILL.md | 2 +- .claude/skills/arrange/SKILL.md | 4 +- .claude/skills/audit/SKILL.md | 4 +- .claude/skills/bolder/SKILL.md | 6 +- .claude/skills/clarify/SKILL.md | 2 +- .claude/skills/colorize/SKILL.md | 2 +- .claude/skills/critique/SKILL.md | 6 +- .claude/skills/critique/reference/personas.md | 2 +- .claude/skills/delight/SKILL.md | 2 +- .claude/skills/distill/SKILL.md | 2 +- .claude/skills/frontend-design/SKILL.md | 147 +----------- .claude/skills/impeccable/SKILL.md | 219 ++++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 .claude/skills/normalize/SKILL.md | 2 +- .claude/skills/onboard/SKILL.md | 2 +- .claude/skills/overdrive/SKILL.md | 2 +- .claude/skills/polish/SKILL.md | 2 +- .claude/skills/quieter/SKILL.md | 2 +- .claude/skills/teach-impeccable/SKILL.md | 68 +----- .claude/skills/typeset/SKILL.md | 4 +- .codex/skills/adapt/SKILL.md | 2 +- .codex/skills/animate/SKILL.md | 2 +- .codex/skills/arrange/SKILL.md | 4 +- .codex/skills/audit/SKILL.md | 4 +- .codex/skills/bolder/SKILL.md | 6 +- .codex/skills/clarify/SKILL.md | 2 +- .codex/skills/colorize/SKILL.md | 2 +- .codex/skills/critique/SKILL.md | 6 +- .codex/skills/critique/reference/personas.md | 2 +- .codex/skills/delight/SKILL.md | 2 +- .codex/skills/distill/SKILL.md | 2 +- .codex/skills/frontend-design/SKILL.md | 147 +----------- .codex/skills/impeccable/SKILL.md | 218 +++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 .codex/skills/normalize/SKILL.md | 2 +- .codex/skills/onboard/SKILL.md | 2 +- .codex/skills/overdrive/SKILL.md | 2 +- .codex/skills/polish/SKILL.md | 2 +- .codex/skills/quieter/SKILL.md | 2 +- .codex/skills/teach-impeccable/SKILL.md | 68 +----- .codex/skills/typeset/SKILL.md | 4 +- .cursor/skills/adapt/SKILL.md | 2 +- .cursor/skills/animate/SKILL.md | 2 +- .cursor/skills/arrange/SKILL.md | 4 +- .cursor/skills/audit/SKILL.md | 4 +- .cursor/skills/bolder/SKILL.md | 6 +- .cursor/skills/clarify/SKILL.md | 2 +- .cursor/skills/colorize/SKILL.md | 2 +- .cursor/skills/critique/SKILL.md | 6 +- .cursor/skills/critique/reference/personas.md | 2 +- .cursor/skills/delight/SKILL.md | 2 +- .cursor/skills/distill/SKILL.md | 2 +- .cursor/skills/frontend-design/SKILL.md | 147 +----------- .cursor/skills/impeccable/SKILL.md | 217 +++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 .cursor/skills/normalize/SKILL.md | 2 +- .cursor/skills/onboard/SKILL.md | 2 +- .cursor/skills/overdrive/SKILL.md | 2 +- .cursor/skills/polish/SKILL.md | 2 +- .cursor/skills/quieter/SKILL.md | 2 +- .cursor/skills/teach-impeccable/SKILL.md | 68 +----- .cursor/skills/typeset/SKILL.md | 4 +- .gemini/skills/adapt/SKILL.md | 2 +- .gemini/skills/animate/SKILL.md | 2 +- .gemini/skills/arrange/SKILL.md | 4 +- .gemini/skills/audit/SKILL.md | 4 +- .gemini/skills/bolder/SKILL.md | 6 +- .gemini/skills/clarify/SKILL.md | 2 +- .gemini/skills/colorize/SKILL.md | 2 +- .gemini/skills/critique/SKILL.md | 6 +- .gemini/skills/critique/reference/personas.md | 2 +- .gemini/skills/delight/SKILL.md | 2 +- .gemini/skills/distill/SKILL.md | 2 +- .gemini/skills/frontend-design/SKILL.md | 146 +----------- .gemini/skills/impeccable/SKILL.md | 216 +++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 .gemini/skills/normalize/SKILL.md | 2 +- .gemini/skills/onboard/SKILL.md | 2 +- .gemini/skills/overdrive/SKILL.md | 2 +- .gemini/skills/polish/SKILL.md | 2 +- .gemini/skills/quieter/SKILL.md | 2 +- .gemini/skills/teach-impeccable/SKILL.md | 68 +----- .gemini/skills/typeset/SKILL.md | 4 +- .kiro/skills/adapt/SKILL.md | 2 +- .kiro/skills/animate/SKILL.md | 2 +- .kiro/skills/arrange/SKILL.md | 4 +- .kiro/skills/audit/SKILL.md | 4 +- .kiro/skills/bolder/SKILL.md | 6 +- .kiro/skills/clarify/SKILL.md | 2 +- .kiro/skills/colorize/SKILL.md | 2 +- .kiro/skills/critique/SKILL.md | 6 +- .kiro/skills/critique/reference/personas.md | 2 +- .kiro/skills/delight/SKILL.md | 2 +- .kiro/skills/distill/SKILL.md | 2 +- .kiro/skills/frontend-design/SKILL.md | 147 +----------- .kiro/skills/impeccable/SKILL.md | 217 +++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 .kiro/skills/normalize/SKILL.md | 2 +- .kiro/skills/onboard/SKILL.md | 2 +- .kiro/skills/overdrive/SKILL.md | 2 +- .kiro/skills/polish/SKILL.md | 2 +- .kiro/skills/quieter/SKILL.md | 2 +- .kiro/skills/teach-impeccable/SKILL.md | 68 +----- .kiro/skills/typeset/SKILL.md | 4 +- .opencode/skills/adapt/SKILL.md | 2 +- .opencode/skills/animate/SKILL.md | 2 +- .opencode/skills/arrange/SKILL.md | 4 +- .opencode/skills/audit/SKILL.md | 4 +- .opencode/skills/bolder/SKILL.md | 6 +- .opencode/skills/clarify/SKILL.md | 2 +- .opencode/skills/colorize/SKILL.md | 2 +- .opencode/skills/critique/SKILL.md | 6 +- .../skills/critique/reference/personas.md | 2 +- .opencode/skills/delight/SKILL.md | 2 +- .opencode/skills/distill/SKILL.md | 2 +- .opencode/skills/frontend-design/SKILL.md | 147 +----------- .opencode/skills/impeccable/SKILL.md | 219 ++++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 .opencode/skills/normalize/SKILL.md | 2 +- .opencode/skills/onboard/SKILL.md | 2 +- .opencode/skills/overdrive/SKILL.md | 2 +- .opencode/skills/polish/SKILL.md | 2 +- .opencode/skills/quieter/SKILL.md | 2 +- .opencode/skills/teach-impeccable/SKILL.md | 68 +----- .opencode/skills/typeset/SKILL.md | 4 +- .pi/skills/adapt/SKILL.md | 2 +- .pi/skills/animate/SKILL.md | 2 +- .pi/skills/arrange/SKILL.md | 4 +- .pi/skills/audit/SKILL.md | 4 +- .pi/skills/bolder/SKILL.md | 6 +- .pi/skills/clarify/SKILL.md | 2 +- .pi/skills/colorize/SKILL.md | 2 +- .pi/skills/critique/SKILL.md | 6 +- .pi/skills/critique/reference/personas.md | 2 +- .pi/skills/delight/SKILL.md | 2 +- .pi/skills/distill/SKILL.md | 2 +- .pi/skills/frontend-design/SKILL.md | 147 +----------- .pi/skills/impeccable/SKILL.md | 217 +++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 .pi/skills/normalize/SKILL.md | 2 +- .pi/skills/onboard/SKILL.md | 2 +- .pi/skills/overdrive/SKILL.md | 2 +- .pi/skills/polish/SKILL.md | 2 +- .pi/skills/quieter/SKILL.md | 2 +- .pi/skills/teach-impeccable/SKILL.md | 68 +----- .pi/skills/typeset/SKILL.md | 4 +- .trae-cn/skills/adapt/SKILL.md | 2 +- .trae-cn/skills/animate/SKILL.md | 2 +- .trae-cn/skills/arrange/SKILL.md | 4 +- .trae-cn/skills/audit/SKILL.md | 4 +- .trae-cn/skills/bolder/SKILL.md | 6 +- .trae-cn/skills/clarify/SKILL.md | 2 +- .trae-cn/skills/colorize/SKILL.md | 2 +- .trae-cn/skills/critique/SKILL.md | 6 +- .../skills/critique/reference/personas.md | 2 +- .trae-cn/skills/delight/SKILL.md | 2 +- .trae-cn/skills/distill/SKILL.md | 2 +- .trae-cn/skills/frontend-design/SKILL.md | 147 +----------- .trae-cn/skills/impeccable/SKILL.md | 219 ++++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 .trae-cn/skills/normalize/SKILL.md | 2 +- .trae-cn/skills/onboard/SKILL.md | 2 +- .trae-cn/skills/overdrive/SKILL.md | 2 +- .trae-cn/skills/polish/SKILL.md | 2 +- .trae-cn/skills/quieter/SKILL.md | 2 +- .trae-cn/skills/teach-impeccable/SKILL.md | 68 +----- .trae-cn/skills/typeset/SKILL.md | 4 +- .trae/skills/adapt/SKILL.md | 2 +- .trae/skills/animate/SKILL.md | 2 +- .trae/skills/arrange/SKILL.md | 4 +- .trae/skills/audit/SKILL.md | 4 +- .trae/skills/bolder/SKILL.md | 6 +- .trae/skills/clarify/SKILL.md | 2 +- .trae/skills/colorize/SKILL.md | 2 +- .trae/skills/critique/SKILL.md | 6 +- .trae/skills/critique/reference/personas.md | 2 +- .trae/skills/delight/SKILL.md | 2 +- .trae/skills/distill/SKILL.md | 2 +- .trae/skills/frontend-design/SKILL.md | 147 +----------- .trae/skills/impeccable/SKILL.md | 219 ++++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 .trae/skills/normalize/SKILL.md | 2 +- .trae/skills/onboard/SKILL.md | 2 +- .trae/skills/overdrive/SKILL.md | 2 +- .trae/skills/polish/SKILL.md | 2 +- .trae/skills/quieter/SKILL.md | 2 +- .trae/skills/teach-impeccable/SKILL.md | 68 +----- .trae/skills/typeset/SKILL.md | 4 +- AGENTS.md | 2 +- NOTICE.md | 2 +- README.md | 32 +-- bin/commands/skills.mjs | 14 +- public/cheatsheet.html | 4 +- public/index.html | 8 +- public/js/components/art-gallery.js | 4 +- public/js/components/framework-viz.js | 4 +- public/js/data.js | 20 +- public/js/demo-renderer.js | 4 +- scripts/lib/utils.js | 8 +- skills-lock.json | 110 +++++++++ source/skills/adapt/SKILL.md | 2 +- source/skills/animate/SKILL.md | 2 +- source/skills/arrange/SKILL.md | 4 +- source/skills/audit/SKILL.md | 4 +- source/skills/bolder/SKILL.md | 6 +- source/skills/clarify/SKILL.md | 2 +- source/skills/colorize/SKILL.md | 2 +- source/skills/critique/SKILL.md | 6 +- source/skills/critique/reference/personas.md | 2 +- source/skills/delight/SKILL.md | 2 +- source/skills/distill/SKILL.md | 2 +- source/skills/frontend-design/SKILL.md | 147 +----------- source/skills/impeccable/SKILL.md | 219 ++++++++++++++++++ .../reference/color-and-contrast.md | 0 .../reference/interaction-design.md | 0 .../reference/motion-design.md | 0 .../reference/responsive-design.md | 0 .../reference/spatial-design.md | 0 .../reference/typography.md | 0 .../reference/ux-writing.md | 0 source/skills/normalize/SKILL.md | 2 +- source/skills/onboard/SKILL.md | 2 +- source/skills/overdrive/SKILL.md | 2 +- source/skills/polish/SKILL.md | 2 +- source/skills/quieter/SKILL.md | 2 +- source/skills/teach-impeccable/SKILL.md | 68 +----- source/skills/typeset/SKILL.md | 4 +- tests/lib/utils.test.js | 36 +-- tests/server/download-validation.test.js | 6 +- tests/skills-cli.test.js | 40 ++-- 314 files changed, 2987 insertions(+), 2602 deletions(-) create mode 100644 .agents/skills/impeccable/SKILL.md rename .agents/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename .agents/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename .agents/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename .agents/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename .agents/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename .agents/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename .agents/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) create mode 100644 .claude/skills/impeccable/SKILL.md rename .claude/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename .claude/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename .claude/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename .claude/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename .claude/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename .claude/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename .claude/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) create mode 100644 .codex/skills/impeccable/SKILL.md rename .codex/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename .codex/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename .codex/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename .codex/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename .codex/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename .codex/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename .codex/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) create mode 100644 .cursor/skills/impeccable/SKILL.md rename .cursor/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename .cursor/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename .cursor/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename .cursor/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename .cursor/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename .cursor/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename .cursor/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) create mode 100644 .gemini/skills/impeccable/SKILL.md rename .gemini/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename .gemini/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename .gemini/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename .gemini/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename .gemini/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename .gemini/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename .gemini/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) create mode 100644 .kiro/skills/impeccable/SKILL.md rename .kiro/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename .kiro/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename .kiro/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename .kiro/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename .kiro/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename .kiro/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename .kiro/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) create mode 100644 .opencode/skills/impeccable/SKILL.md rename .opencode/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename .opencode/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename .opencode/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename .opencode/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename .opencode/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename .opencode/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename .opencode/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) create mode 100644 .pi/skills/impeccable/SKILL.md rename .pi/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename .pi/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename .pi/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename .pi/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename .pi/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename .pi/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename .pi/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) create mode 100644 .trae-cn/skills/impeccable/SKILL.md rename .trae-cn/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename .trae-cn/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename .trae-cn/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename .trae-cn/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename .trae-cn/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename .trae-cn/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename .trae-cn/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) create mode 100644 .trae/skills/impeccable/SKILL.md rename .trae/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename .trae/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename .trae/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename .trae/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename .trae/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename .trae/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename .trae/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) create mode 100644 skills-lock.json create mode 100644 source/skills/impeccable/SKILL.md rename source/skills/{frontend-design => impeccable}/reference/color-and-contrast.md (100%) rename source/skills/{frontend-design => impeccable}/reference/interaction-design.md (100%) rename source/skills/{frontend-design => impeccable}/reference/motion-design.md (100%) rename source/skills/{frontend-design => impeccable}/reference/responsive-design.md (100%) rename source/skills/{frontend-design => impeccable}/reference/spatial-design.md (100%) rename source/skills/{frontend-design => impeccable}/reference/typography.md (100%) rename source/skills/{frontend-design => impeccable}/reference/ux-writing.md (100%) diff --git a/.agents/skills/adapt/SKILL.md b/.agents/skills/adapt/SKILL.md index 165c66dcc..537c15b32 100644 --- a/.agents/skills/adapt/SKILL.md +++ b/.agents/skills/adapt/SKILL.md @@ -9,7 +9,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/.agents/skills/animate/SKILL.md b/.agents/skills/animate/SKILL.md index 3d006d15e..a28332e96 100644 --- a/.agents/skills/animate/SKILL.md +++ b/.agents/skills/animate/SKILL.md @@ -9,7 +9,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: performance constraints. --- diff --git a/.agents/skills/arrange/SKILL.md b/.agents/skills/arrange/SKILL.md index ce4cf3ad6..d63c1aab0 100644 --- a/.agents/skills/arrange/SKILL.md +++ b/.agents/skills/arrange/SKILL.md @@ -9,7 +9,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/.agents/skills/audit/SKILL.md b/.agents/skills/audit/SKILL.md index 1debe043e..4d54dca12 100644 --- a/.agents/skills/audit/SKILL.md +++ b/.agents/skills/audit/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[area (feature, page, component...)]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -65,7 +65,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/.agents/skills/bolder/SKILL.md b/.agents/skills/bolder/SKILL.md index 0b03f025f..94c6dc8f2 100644 --- a/.agents/skills/bolder/SKILL.md +++ b/.agents/skills/bolder/SKILL.md @@ -9,7 +9,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -35,7 +35,7 @@ If any of these are unclear from the codebase, ask the user directly to clarify **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -53,7 +53,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/.agents/skills/clarify/SKILL.md b/.agents/skills/clarify/SKILL.md index 4db9228d6..0ee5eb997 100644 --- a/.agents/skills/clarify/SKILL.md +++ b/.agents/skills/clarify/SKILL.md @@ -9,7 +9,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/.agents/skills/colorize/SKILL.md b/.agents/skills/colorize/SKILL.md index 0b092ac08..726dfaca0 100644 --- a/.agents/skills/colorize/SKILL.md +++ b/.agents/skills/colorize/SKILL.md @@ -9,7 +9,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: existing brand colors. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/.agents/skills/critique/SKILL.md b/.agents/skills/critique/SKILL.md index 4c2c40285..4b89ec788 100644 --- a/.agents/skills/critique/SKILL.md +++ b/.agents/skills/critique/SKILL.md @@ -9,7 +9,7 @@ argument-hint: "[area (feature, page, component...)]" ### Step 1: Preparation -Invoke /frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -27,7 +27,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -145,7 +145,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `.github/copilot-instructions.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `.github/copilot-instructions.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/.agents/skills/critique/reference/personas.md b/.agents/skills/critique/reference/personas.md index eb2f2b6d1..a22606aa2 100644 --- a/.agents/skills/critique/reference/personas.md +++ b/.agents/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `.github/copilot-instructions.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `.github/copilot-instructions.md` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/.agents/skills/delight/SKILL.md b/.agents/skills/delight/SKILL.md index fe39492d7..161a4b2b4 100644 --- a/.agents/skills/delight/SKILL.md +++ b/.agents/skills/delight/SKILL.md @@ -9,7 +9,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/.agents/skills/distill/SKILL.md b/.agents/skills/distill/SKILL.md index fd2a8e47f..fbe16f3e8 100644 --- a/.agents/skills/distill/SKILL.md +++ b/.agents/skills/distill/SKILL.md @@ -9,7 +9,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.agents/skills/frontend-design/SKILL.md b/.agents/skills/frontend-design/SKILL.md index dd7c5dd4c..459cf0542 100644 --- a/.agents/skills/frontend-design/SKILL.md +++ b/.agents/skills/frontend-design/SKILL.md @@ -1,147 +1,12 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. -license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +description: DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead. --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `/impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `/impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `/impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run /teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: the model is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file +Do NOT attempt any design work from this skill. Redirect to `/impeccable` instead. \ No newline at end of file diff --git a/.agents/skills/impeccable/SKILL.md b/.agents/skills/impeccable/SKILL.md new file mode 100644 index 000000000..f7e88c29c --- /dev/null +++ b/.agents/skills/impeccable/SKILL.md @@ -0,0 +1,219 @@ +--- +name: impeccable +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +user-invocable: true +argument-hint: "[teach]" +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: the model is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .github/copilot-instructions.md. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/.agents/skills/frontend-design/reference/color-and-contrast.md b/.agents/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from .agents/skills/frontend-design/reference/color-and-contrast.md rename to .agents/skills/impeccable/reference/color-and-contrast.md diff --git a/.agents/skills/frontend-design/reference/interaction-design.md b/.agents/skills/impeccable/reference/interaction-design.md similarity index 100% rename from .agents/skills/frontend-design/reference/interaction-design.md rename to .agents/skills/impeccable/reference/interaction-design.md diff --git a/.agents/skills/frontend-design/reference/motion-design.md b/.agents/skills/impeccable/reference/motion-design.md similarity index 100% rename from .agents/skills/frontend-design/reference/motion-design.md rename to .agents/skills/impeccable/reference/motion-design.md diff --git a/.agents/skills/frontend-design/reference/responsive-design.md b/.agents/skills/impeccable/reference/responsive-design.md similarity index 100% rename from .agents/skills/frontend-design/reference/responsive-design.md rename to .agents/skills/impeccable/reference/responsive-design.md diff --git a/.agents/skills/frontend-design/reference/spatial-design.md b/.agents/skills/impeccable/reference/spatial-design.md similarity index 100% rename from .agents/skills/frontend-design/reference/spatial-design.md rename to .agents/skills/impeccable/reference/spatial-design.md diff --git a/.agents/skills/frontend-design/reference/typography.md b/.agents/skills/impeccable/reference/typography.md similarity index 100% rename from .agents/skills/frontend-design/reference/typography.md rename to .agents/skills/impeccable/reference/typography.md diff --git a/.agents/skills/frontend-design/reference/ux-writing.md b/.agents/skills/impeccable/reference/ux-writing.md similarity index 100% rename from .agents/skills/frontend-design/reference/ux-writing.md rename to .agents/skills/impeccable/reference/ux-writing.md diff --git a/.agents/skills/normalize/SKILL.md b/.agents/skills/normalize/SKILL.md index 4015c54a3..cbc512296 100644 --- a/.agents/skills/normalize/SKILL.md +++ b/.agents/skills/normalize/SKILL.md @@ -9,7 +9,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.agents/skills/onboard/SKILL.md b/.agents/skills/onboard/SKILL.md index 14666050b..01a1d2dd6 100644 --- a/.agents/skills/onboard/SKILL.md +++ b/.agents/skills/onboard/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/.agents/skills/overdrive/SKILL.md b/.agents/skills/overdrive/SKILL.md index fd9199ec6..a389e6346 100644 --- a/.agents/skills/overdrive/SKILL.md +++ b/.agents/skills/overdrive/SKILL.md @@ -16,7 +16,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/.agents/skills/polish/SKILL.md b/.agents/skills/polish/SKILL.md index fcaae6e88..1e8751a6a 100644 --- a/.agents/skills/polish/SKILL.md +++ b/.agents/skills/polish/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/.agents/skills/quieter/SKILL.md b/.agents/skills/quieter/SKILL.md index 555ca446e..314f574be 100644 --- a/.agents/skills/quieter/SKILL.md +++ b/.agents/skills/quieter/SKILL.md @@ -9,7 +9,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.agents/skills/teach-impeccable/SKILL.md b/.agents/skills/teach-impeccable/SKILL.md index 423a9a05a..4f39eb5ae 100644 --- a/.agents/skills/teach-impeccable/SKILL.md +++ b/.agents/skills/teach-impeccable/SKILL.md @@ -1,71 +1,11 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill. user-invocable: true --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `/impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .github/copilot-instructions.md. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file +> The `/teach-impeccable` command has been renamed to `/impeccable teach`. Please use that instead. \ No newline at end of file diff --git a/.agents/skills/typeset/SKILL.md b/.agents/skills/typeset/SKILL.md index 139153a28..9d89fafad 100644 --- a/.agents/skills/typeset/SKILL.md +++ b/.agents/skills/typeset/SKILL.md @@ -9,7 +9,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6237381be..97a620925 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "plugins": [ { "name": "impeccable", - "description": "Design vocabulary and skills for frontend development. Includes 20 commands (/polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced frontend-design skill with curated anti-patterns.", + "description": "Design vocabulary and skills for frontend development. Includes 20 commands (/polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced impeccable skill with curated anti-patterns.", "version": "2.0.2", "author": { "name": "Paul Bakaus", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index cebc4b76e..ae53a9256 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "impeccable", - "description": "Design vocabulary and skills for frontend development. Includes 21 skills (20 user-invocable: /polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced frontend-design skill with curated anti-patterns.", + "description": "Design vocabulary and skills for frontend development. Includes 21 skills (20 user-invocable: /polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced impeccable skill with curated anti-patterns.", "version": "2.0.2", "author": { "name": "Paul Bakaus", diff --git a/.claude/skills/adapt/SKILL.md b/.claude/skills/adapt/SKILL.md index 165c66dcc..537c15b32 100644 --- a/.claude/skills/adapt/SKILL.md +++ b/.claude/skills/adapt/SKILL.md @@ -9,7 +9,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/.claude/skills/animate/SKILL.md b/.claude/skills/animate/SKILL.md index c2aeb2a62..e1e6b6294 100644 --- a/.claude/skills/animate/SKILL.md +++ b/.claude/skills/animate/SKILL.md @@ -9,7 +9,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: performance constraints. --- diff --git a/.claude/skills/arrange/SKILL.md b/.claude/skills/arrange/SKILL.md index ce4cf3ad6..d63c1aab0 100644 --- a/.claude/skills/arrange/SKILL.md +++ b/.claude/skills/arrange/SKILL.md @@ -9,7 +9,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/.claude/skills/audit/SKILL.md b/.claude/skills/audit/SKILL.md index 1debe043e..4d54dca12 100644 --- a/.claude/skills/audit/SKILL.md +++ b/.claude/skills/audit/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[area (feature, page, component...)]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -65,7 +65,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/.claude/skills/bolder/SKILL.md b/.claude/skills/bolder/SKILL.md index cc5be2f3d..b36ede85a 100644 --- a/.claude/skills/bolder/SKILL.md +++ b/.claude/skills/bolder/SKILL.md @@ -9,7 +9,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -35,7 +35,7 @@ If any of these are unclear from the codebase, STOP and call the AskUserQuestion **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -53,7 +53,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/.claude/skills/clarify/SKILL.md b/.claude/skills/clarify/SKILL.md index 4db9228d6..0ee5eb997 100644 --- a/.claude/skills/clarify/SKILL.md +++ b/.claude/skills/clarify/SKILL.md @@ -9,7 +9,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/.claude/skills/colorize/SKILL.md b/.claude/skills/colorize/SKILL.md index 01205dd89..a2d4a157a 100644 --- a/.claude/skills/colorize/SKILL.md +++ b/.claude/skills/colorize/SKILL.md @@ -9,7 +9,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: existing brand colors. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md index 6ff21d418..0800af4a8 100644 --- a/.claude/skills/critique/SKILL.md +++ b/.claude/skills/critique/SKILL.md @@ -14,7 +14,7 @@ allowed-tools: ### Step 1: Preparation -Invoke /frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -32,7 +32,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -150,7 +150,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `CLAUDE.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `CLAUDE.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/.claude/skills/critique/reference/personas.md b/.claude/skills/critique/reference/personas.md index 1960220aa..eb8173b73 100644 --- a/.claude/skills/critique/reference/personas.md +++ b/.claude/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `CLAUDE.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `CLAUDE.md` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/.claude/skills/delight/SKILL.md b/.claude/skills/delight/SKILL.md index ff33d7288..c5d27b03f 100644 --- a/.claude/skills/delight/SKILL.md +++ b/.claude/skills/delight/SKILL.md @@ -9,7 +9,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/.claude/skills/distill/SKILL.md b/.claude/skills/distill/SKILL.md index acd814616..343f8a998 100644 --- a/.claude/skills/distill/SKILL.md +++ b/.claude/skills/distill/SKILL.md @@ -9,7 +9,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.claude/skills/frontend-design/SKILL.md b/.claude/skills/frontend-design/SKILL.md index f7ad80468..459cf0542 100644 --- a/.claude/skills/frontend-design/SKILL.md +++ b/.claude/skills/frontend-design/SKILL.md @@ -1,147 +1,12 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. -license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +description: DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead. --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `/impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `/impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `/impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run /teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: Claude is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file +Do NOT attempt any design work from this skill. Redirect to `/impeccable` instead. \ No newline at end of file diff --git a/.claude/skills/impeccable/SKILL.md b/.claude/skills/impeccable/SKILL.md new file mode 100644 index 000000000..e3b166a56 --- /dev/null +++ b/.claude/skills/impeccable/SKILL.md @@ -0,0 +1,219 @@ +--- +name: impeccable +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +user-invocable: true +argument-hint: "[teach]" +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: Claude is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +STOP and call the AskUserQuestion tool to clarify. Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then STOP and call the AskUserQuestion tool to clarify. whether they'd also like the Design Context appended to CLAUDE.md. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/.claude/skills/frontend-design/reference/color-and-contrast.md b/.claude/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from .claude/skills/frontend-design/reference/color-and-contrast.md rename to .claude/skills/impeccable/reference/color-and-contrast.md diff --git a/.claude/skills/frontend-design/reference/interaction-design.md b/.claude/skills/impeccable/reference/interaction-design.md similarity index 100% rename from .claude/skills/frontend-design/reference/interaction-design.md rename to .claude/skills/impeccable/reference/interaction-design.md diff --git a/.claude/skills/frontend-design/reference/motion-design.md b/.claude/skills/impeccable/reference/motion-design.md similarity index 100% rename from .claude/skills/frontend-design/reference/motion-design.md rename to .claude/skills/impeccable/reference/motion-design.md diff --git a/.claude/skills/frontend-design/reference/responsive-design.md b/.claude/skills/impeccable/reference/responsive-design.md similarity index 100% rename from .claude/skills/frontend-design/reference/responsive-design.md rename to .claude/skills/impeccable/reference/responsive-design.md diff --git a/.claude/skills/frontend-design/reference/spatial-design.md b/.claude/skills/impeccable/reference/spatial-design.md similarity index 100% rename from .claude/skills/frontend-design/reference/spatial-design.md rename to .claude/skills/impeccable/reference/spatial-design.md diff --git a/.claude/skills/frontend-design/reference/typography.md b/.claude/skills/impeccable/reference/typography.md similarity index 100% rename from .claude/skills/frontend-design/reference/typography.md rename to .claude/skills/impeccable/reference/typography.md diff --git a/.claude/skills/frontend-design/reference/ux-writing.md b/.claude/skills/impeccable/reference/ux-writing.md similarity index 100% rename from .claude/skills/frontend-design/reference/ux-writing.md rename to .claude/skills/impeccable/reference/ux-writing.md diff --git a/.claude/skills/normalize/SKILL.md b/.claude/skills/normalize/SKILL.md index 4015c54a3..cbc512296 100644 --- a/.claude/skills/normalize/SKILL.md +++ b/.claude/skills/normalize/SKILL.md @@ -9,7 +9,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.claude/skills/onboard/SKILL.md b/.claude/skills/onboard/SKILL.md index 14666050b..01a1d2dd6 100644 --- a/.claude/skills/onboard/SKILL.md +++ b/.claude/skills/onboard/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/.claude/skills/overdrive/SKILL.md b/.claude/skills/overdrive/SKILL.md index e0a5d9c80..fc66051a7 100644 --- a/.claude/skills/overdrive/SKILL.md +++ b/.claude/skills/overdrive/SKILL.md @@ -16,7 +16,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/.claude/skills/polish/SKILL.md b/.claude/skills/polish/SKILL.md index fcaae6e88..1e8751a6a 100644 --- a/.claude/skills/polish/SKILL.md +++ b/.claude/skills/polish/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/.claude/skills/quieter/SKILL.md b/.claude/skills/quieter/SKILL.md index 9090eacdb..c969932a4 100644 --- a/.claude/skills/quieter/SKILL.md +++ b/.claude/skills/quieter/SKILL.md @@ -9,7 +9,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.claude/skills/teach-impeccable/SKILL.md b/.claude/skills/teach-impeccable/SKILL.md index 96f31fedf..4f39eb5ae 100644 --- a/.claude/skills/teach-impeccable/SKILL.md +++ b/.claude/skills/teach-impeccable/SKILL.md @@ -1,71 +1,11 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill. user-invocable: true --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `/impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -STOP and call the AskUserQuestion tool to clarify. Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then STOP and call the AskUserQuestion tool to clarify. whether they'd also like the Design Context appended to CLAUDE.md. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file +> The `/teach-impeccable` command has been renamed to `/impeccable teach`. Please use that instead. \ No newline at end of file diff --git a/.claude/skills/typeset/SKILL.md b/.claude/skills/typeset/SKILL.md index 139153a28..9d89fafad 100644 --- a/.claude/skills/typeset/SKILL.md +++ b/.claude/skills/typeset/SKILL.md @@ -9,7 +9,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/.codex/skills/adapt/SKILL.md b/.codex/skills/adapt/SKILL.md index 12c157628..9c40f3e32 100644 --- a/.codex/skills/adapt/SKILL.md +++ b/.codex/skills/adapt/SKILL.md @@ -8,7 +8,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/.codex/skills/animate/SKILL.md b/.codex/skills/animate/SKILL.md index 5055541c2..f7bd6667e 100644 --- a/.codex/skills/animate/SKILL.md +++ b/.codex/skills/animate/SKILL.md @@ -8,7 +8,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. Additionally gather: performance constraints. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. Additionally gather: performance constraints. --- diff --git a/.codex/skills/arrange/SKILL.md b/.codex/skills/arrange/SKILL.md index a9f2f3a07..0b371c586 100644 --- a/.codex/skills/arrange/SKILL.md +++ b/.codex/skills/arrange/SKILL.md @@ -8,7 +8,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. --- @@ -45,7 +45,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/.codex/skills/audit/SKILL.md b/.codex/skills/audit/SKILL.md index def1967dc..2a5bfe3a4 100644 --- a/.codex/skills/audit/SKILL.md +++ b/.codex/skills/audit/SKILL.md @@ -6,7 +6,7 @@ argument-hint: "[area (feature, page, component...)]" ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. --- @@ -64,7 +64,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/.codex/skills/bolder/SKILL.md b/.codex/skills/bolder/SKILL.md index 9fccbf5fc..ae89f5a71 100644 --- a/.codex/skills/bolder/SKILL.md +++ b/.codex/skills/bolder/SKILL.md @@ -8,7 +8,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. --- @@ -34,7 +34,7 @@ If any of these are unclear from the codebase, ask the user directly to clarify **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -52,7 +52,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/.codex/skills/clarify/SKILL.md b/.codex/skills/clarify/SKILL.md index 145c72aef..ded306f81 100644 --- a/.codex/skills/clarify/SKILL.md +++ b/.codex/skills/clarify/SKILL.md @@ -8,7 +8,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/.codex/skills/colorize/SKILL.md b/.codex/skills/colorize/SKILL.md index 9c76379bc..a71749893 100644 --- a/.codex/skills/colorize/SKILL.md +++ b/.codex/skills/colorize/SKILL.md @@ -8,7 +8,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. Additionally gather: existing brand colors. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/.codex/skills/critique/SKILL.md b/.codex/skills/critique/SKILL.md index ccb67daaa..0034c602d 100644 --- a/.codex/skills/critique/SKILL.md +++ b/.codex/skills/critique/SKILL.md @@ -8,7 +8,7 @@ argument-hint: "[area (feature, page, component...)]" ### Step 1: Preparation -Invoke $frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run $teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke $impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run $impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -26,7 +26,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -144,7 +144,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/.codex/skills/critique/reference/personas.md b/.codex/skills/critique/reference/personas.md index 2d0f9cbf3..5e91eb651 100644 --- a/.codex/skills/critique/reference/personas.md +++ b/.codex/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `AGENTS.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `AGENTS.md` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/.codex/skills/delight/SKILL.md b/.codex/skills/delight/SKILL.md index 9a3b44371..1f7a5baf6 100644 --- a/.codex/skills/delight/SKILL.md +++ b/.codex/skills/delight/SKILL.md @@ -8,7 +8,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/.codex/skills/distill/SKILL.md b/.codex/skills/distill/SKILL.md index 6ece45177..ac0b8f0d8 100644 --- a/.codex/skills/distill/SKILL.md +++ b/.codex/skills/distill/SKILL.md @@ -8,7 +8,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. --- diff --git a/.codex/skills/frontend-design/SKILL.md b/.codex/skills/frontend-design/SKILL.md index a776c78dd..606847842 100644 --- a/.codex/skills/frontend-design/SKILL.md +++ b/.codex/skills/frontend-design/SKILL.md @@ -1,147 +1,12 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. -license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +description: DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead. --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `$impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `$impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `$impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run $teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: GPT is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file +Do NOT attempt any design work from this skill. Redirect to `$impeccable` instead. \ No newline at end of file diff --git a/.codex/skills/impeccable/SKILL.md b/.codex/skills/impeccable/SKILL.md new file mode 100644 index 000000000..511181276 --- /dev/null +++ b/.codex/skills/impeccable/SKILL.md @@ -0,0 +1,218 @@ +--- +name: impeccable +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +argument-hint: "[teach]" +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run $impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: GPT is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `$impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to AGENTS.md. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/.codex/skills/frontend-design/reference/color-and-contrast.md b/.codex/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from .codex/skills/frontend-design/reference/color-and-contrast.md rename to .codex/skills/impeccable/reference/color-and-contrast.md diff --git a/.codex/skills/frontend-design/reference/interaction-design.md b/.codex/skills/impeccable/reference/interaction-design.md similarity index 100% rename from .codex/skills/frontend-design/reference/interaction-design.md rename to .codex/skills/impeccable/reference/interaction-design.md diff --git a/.codex/skills/frontend-design/reference/motion-design.md b/.codex/skills/impeccable/reference/motion-design.md similarity index 100% rename from .codex/skills/frontend-design/reference/motion-design.md rename to .codex/skills/impeccable/reference/motion-design.md diff --git a/.codex/skills/frontend-design/reference/responsive-design.md b/.codex/skills/impeccable/reference/responsive-design.md similarity index 100% rename from .codex/skills/frontend-design/reference/responsive-design.md rename to .codex/skills/impeccable/reference/responsive-design.md diff --git a/.codex/skills/frontend-design/reference/spatial-design.md b/.codex/skills/impeccable/reference/spatial-design.md similarity index 100% rename from .codex/skills/frontend-design/reference/spatial-design.md rename to .codex/skills/impeccable/reference/spatial-design.md diff --git a/.codex/skills/frontend-design/reference/typography.md b/.codex/skills/impeccable/reference/typography.md similarity index 100% rename from .codex/skills/frontend-design/reference/typography.md rename to .codex/skills/impeccable/reference/typography.md diff --git a/.codex/skills/frontend-design/reference/ux-writing.md b/.codex/skills/impeccable/reference/ux-writing.md similarity index 100% rename from .codex/skills/frontend-design/reference/ux-writing.md rename to .codex/skills/impeccable/reference/ux-writing.md diff --git a/.codex/skills/normalize/SKILL.md b/.codex/skills/normalize/SKILL.md index 3cb987a03..b310d331e 100644 --- a/.codex/skills/normalize/SKILL.md +++ b/.codex/skills/normalize/SKILL.md @@ -8,7 +8,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. --- diff --git a/.codex/skills/onboard/SKILL.md b/.codex/skills/onboard/SKILL.md index 35d4968d9..8cc4f2105 100644 --- a/.codex/skills/onboard/SKILL.md +++ b/.codex/skills/onboard/SKILL.md @@ -6,7 +6,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/.codex/skills/overdrive/SKILL.md b/.codex/skills/overdrive/SKILL.md index df38a086e..d17acdd93 100644 --- a/.codex/skills/overdrive/SKILL.md +++ b/.codex/skills/overdrive/SKILL.md @@ -15,7 +15,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/.codex/skills/polish/SKILL.md b/.codex/skills/polish/SKILL.md index 5010db3f0..56c006041 100644 --- a/.codex/skills/polish/SKILL.md +++ b/.codex/skills/polish/SKILL.md @@ -6,7 +6,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/.codex/skills/quieter/SKILL.md b/.codex/skills/quieter/SKILL.md index 5390054ed..497e91e8a 100644 --- a/.codex/skills/quieter/SKILL.md +++ b/.codex/skills/quieter/SKILL.md @@ -8,7 +8,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. --- diff --git a/.codex/skills/teach-impeccable/SKILL.md b/.codex/skills/teach-impeccable/SKILL.md index 5267bf599..1f7a00d09 100644 --- a/.codex/skills/teach-impeccable/SKILL.md +++ b/.codex/skills/teach-impeccable/SKILL.md @@ -1,70 +1,10 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill. --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `$impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to AGENTS.md. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file +> The `$teach-impeccable` command has been renamed to `$impeccable teach`. Please use that instead. \ No newline at end of file diff --git a/.codex/skills/typeset/SKILL.md b/.codex/skills/typeset/SKILL.md index 239178118..53ff177c8 100644 --- a/.codex/skills/typeset/SKILL.md +++ b/.codex/skills/typeset/SKILL.md @@ -8,7 +8,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. +Invoke $impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $impeccable teach first. --- @@ -45,7 +45,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/.cursor/skills/adapt/SKILL.md b/.cursor/skills/adapt/SKILL.md index 2b30e16f4..a6de081bf 100644 --- a/.cursor/skills/adapt/SKILL.md +++ b/.cursor/skills/adapt/SKILL.md @@ -7,7 +7,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/.cursor/skills/animate/SKILL.md b/.cursor/skills/animate/SKILL.md index f22c210db..21cb29942 100644 --- a/.cursor/skills/animate/SKILL.md +++ b/.cursor/skills/animate/SKILL.md @@ -7,7 +7,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: performance constraints. --- diff --git a/.cursor/skills/arrange/SKILL.md b/.cursor/skills/arrange/SKILL.md index 1d3a6beb2..f80a260e9 100644 --- a/.cursor/skills/arrange/SKILL.md +++ b/.cursor/skills/arrange/SKILL.md @@ -7,7 +7,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -44,7 +44,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/.cursor/skills/audit/SKILL.md b/.cursor/skills/audit/SKILL.md index 6dc747d60..1bcc446e2 100644 --- a/.cursor/skills/audit/SKILL.md +++ b/.cursor/skills/audit/SKILL.md @@ -5,7 +5,7 @@ description: Run technical quality checks across accessibility, performance, the ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -63,7 +63,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/.cursor/skills/bolder/SKILL.md b/.cursor/skills/bolder/SKILL.md index a43c8003d..281f9d2a4 100644 --- a/.cursor/skills/bolder/SKILL.md +++ b/.cursor/skills/bolder/SKILL.md @@ -7,7 +7,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -33,7 +33,7 @@ If any of these are unclear from the codebase, ask the user directly to clarify **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -51,7 +51,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/.cursor/skills/clarify/SKILL.md b/.cursor/skills/clarify/SKILL.md index 462a515fa..23e6b330c 100644 --- a/.cursor/skills/clarify/SKILL.md +++ b/.cursor/skills/clarify/SKILL.md @@ -7,7 +7,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/.cursor/skills/colorize/SKILL.md b/.cursor/skills/colorize/SKILL.md index 39cabdaf3..7dea7b6c4 100644 --- a/.cursor/skills/colorize/SKILL.md +++ b/.cursor/skills/colorize/SKILL.md @@ -7,7 +7,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: existing brand colors. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/.cursor/skills/critique/SKILL.md b/.cursor/skills/critique/SKILL.md index 3475368f9..c6825481d 100644 --- a/.cursor/skills/critique/SKILL.md +++ b/.cursor/skills/critique/SKILL.md @@ -7,7 +7,7 @@ description: Evaluate design from a UX perspective, assessing visual hierarchy, ### Step 1: Preparation -Invoke /frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -25,7 +25,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -143,7 +143,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `.cursorrules` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `.cursorrules` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/.cursor/skills/critique/reference/personas.md b/.cursor/skills/critique/reference/personas.md index 84689b598..32d9b6ee6 100644 --- a/.cursor/skills/critique/reference/personas.md +++ b/.cursor/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `.cursorrules` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `.cursorrules` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/.cursor/skills/delight/SKILL.md b/.cursor/skills/delight/SKILL.md index d3d76c3ae..71b990589 100644 --- a/.cursor/skills/delight/SKILL.md +++ b/.cursor/skills/delight/SKILL.md @@ -7,7 +7,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/.cursor/skills/distill/SKILL.md b/.cursor/skills/distill/SKILL.md index 05b49d392..8ee7f4d38 100644 --- a/.cursor/skills/distill/SKILL.md +++ b/.cursor/skills/distill/SKILL.md @@ -7,7 +7,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.cursor/skills/frontend-design/SKILL.md b/.cursor/skills/frontend-design/SKILL.md index dd7c5dd4c..459cf0542 100644 --- a/.cursor/skills/frontend-design/SKILL.md +++ b/.cursor/skills/frontend-design/SKILL.md @@ -1,147 +1,12 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. -license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +description: DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead. --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `/impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `/impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `/impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run /teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: the model is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file +Do NOT attempt any design work from this skill. Redirect to `/impeccable` instead. \ No newline at end of file diff --git a/.cursor/skills/impeccable/SKILL.md b/.cursor/skills/impeccable/SKILL.md new file mode 100644 index 000000000..b78fe17fc --- /dev/null +++ b/.cursor/skills/impeccable/SKILL.md @@ -0,0 +1,217 @@ +--- +name: impeccable +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: the model is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .cursorrules. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/.cursor/skills/frontend-design/reference/color-and-contrast.md b/.cursor/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from .cursor/skills/frontend-design/reference/color-and-contrast.md rename to .cursor/skills/impeccable/reference/color-and-contrast.md diff --git a/.cursor/skills/frontend-design/reference/interaction-design.md b/.cursor/skills/impeccable/reference/interaction-design.md similarity index 100% rename from .cursor/skills/frontend-design/reference/interaction-design.md rename to .cursor/skills/impeccable/reference/interaction-design.md diff --git a/.cursor/skills/frontend-design/reference/motion-design.md b/.cursor/skills/impeccable/reference/motion-design.md similarity index 100% rename from .cursor/skills/frontend-design/reference/motion-design.md rename to .cursor/skills/impeccable/reference/motion-design.md diff --git a/.cursor/skills/frontend-design/reference/responsive-design.md b/.cursor/skills/impeccable/reference/responsive-design.md similarity index 100% rename from .cursor/skills/frontend-design/reference/responsive-design.md rename to .cursor/skills/impeccable/reference/responsive-design.md diff --git a/.cursor/skills/frontend-design/reference/spatial-design.md b/.cursor/skills/impeccable/reference/spatial-design.md similarity index 100% rename from .cursor/skills/frontend-design/reference/spatial-design.md rename to .cursor/skills/impeccable/reference/spatial-design.md diff --git a/.cursor/skills/frontend-design/reference/typography.md b/.cursor/skills/impeccable/reference/typography.md similarity index 100% rename from .cursor/skills/frontend-design/reference/typography.md rename to .cursor/skills/impeccable/reference/typography.md diff --git a/.cursor/skills/frontend-design/reference/ux-writing.md b/.cursor/skills/impeccable/reference/ux-writing.md similarity index 100% rename from .cursor/skills/frontend-design/reference/ux-writing.md rename to .cursor/skills/impeccable/reference/ux-writing.md diff --git a/.cursor/skills/normalize/SKILL.md b/.cursor/skills/normalize/SKILL.md index 260a96fec..c3e3c6256 100644 --- a/.cursor/skills/normalize/SKILL.md +++ b/.cursor/skills/normalize/SKILL.md @@ -7,7 +7,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.cursor/skills/onboard/SKILL.md b/.cursor/skills/onboard/SKILL.md index 2e9f7773d..cd529ecb9 100644 --- a/.cursor/skills/onboard/SKILL.md +++ b/.cursor/skills/onboard/SKILL.md @@ -5,7 +5,7 @@ description: Designs and improves onboarding flows, empty states, and first-run ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/.cursor/skills/overdrive/SKILL.md b/.cursor/skills/overdrive/SKILL.md index f890ceae4..77c16f661 100644 --- a/.cursor/skills/overdrive/SKILL.md +++ b/.cursor/skills/overdrive/SKILL.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/.cursor/skills/polish/SKILL.md b/.cursor/skills/polish/SKILL.md index fe7c63210..53c97fec8 100644 --- a/.cursor/skills/polish/SKILL.md +++ b/.cursor/skills/polish/SKILL.md @@ -5,7 +5,7 @@ description: Performs a final quality pass fixing alignment, spacing, consistenc ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/.cursor/skills/quieter/SKILL.md b/.cursor/skills/quieter/SKILL.md index 22375f005..0fad7086c 100644 --- a/.cursor/skills/quieter/SKILL.md +++ b/.cursor/skills/quieter/SKILL.md @@ -7,7 +7,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.cursor/skills/teach-impeccable/SKILL.md b/.cursor/skills/teach-impeccable/SKILL.md index 114f0fcba..0847a769f 100644 --- a/.cursor/skills/teach-impeccable/SKILL.md +++ b/.cursor/skills/teach-impeccable/SKILL.md @@ -1,70 +1,10 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill. --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `/impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .cursorrules. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file +> The `/teach-impeccable` command has been renamed to `/impeccable teach`. Please use that instead. \ No newline at end of file diff --git a/.cursor/skills/typeset/SKILL.md b/.cursor/skills/typeset/SKILL.md index 2acf08b3e..d534c5002 100644 --- a/.cursor/skills/typeset/SKILL.md +++ b/.cursor/skills/typeset/SKILL.md @@ -7,7 +7,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -44,7 +44,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/.gemini/skills/adapt/SKILL.md b/.gemini/skills/adapt/SKILL.md index 2b30e16f4..a6de081bf 100644 --- a/.gemini/skills/adapt/SKILL.md +++ b/.gemini/skills/adapt/SKILL.md @@ -7,7 +7,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/.gemini/skills/animate/SKILL.md b/.gemini/skills/animate/SKILL.md index f22c210db..21cb29942 100644 --- a/.gemini/skills/animate/SKILL.md +++ b/.gemini/skills/animate/SKILL.md @@ -7,7 +7,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: performance constraints. --- diff --git a/.gemini/skills/arrange/SKILL.md b/.gemini/skills/arrange/SKILL.md index 1d3a6beb2..f80a260e9 100644 --- a/.gemini/skills/arrange/SKILL.md +++ b/.gemini/skills/arrange/SKILL.md @@ -7,7 +7,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -44,7 +44,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/.gemini/skills/audit/SKILL.md b/.gemini/skills/audit/SKILL.md index 6dc747d60..1bcc446e2 100644 --- a/.gemini/skills/audit/SKILL.md +++ b/.gemini/skills/audit/SKILL.md @@ -5,7 +5,7 @@ description: Run technical quality checks across accessibility, performance, the ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -63,7 +63,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/.gemini/skills/bolder/SKILL.md b/.gemini/skills/bolder/SKILL.md index a43c8003d..281f9d2a4 100644 --- a/.gemini/skills/bolder/SKILL.md +++ b/.gemini/skills/bolder/SKILL.md @@ -7,7 +7,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -33,7 +33,7 @@ If any of these are unclear from the codebase, ask the user directly to clarify **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -51,7 +51,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/.gemini/skills/clarify/SKILL.md b/.gemini/skills/clarify/SKILL.md index 462a515fa..23e6b330c 100644 --- a/.gemini/skills/clarify/SKILL.md +++ b/.gemini/skills/clarify/SKILL.md @@ -7,7 +7,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/.gemini/skills/colorize/SKILL.md b/.gemini/skills/colorize/SKILL.md index 39cabdaf3..7dea7b6c4 100644 --- a/.gemini/skills/colorize/SKILL.md +++ b/.gemini/skills/colorize/SKILL.md @@ -7,7 +7,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: existing brand colors. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/.gemini/skills/critique/SKILL.md b/.gemini/skills/critique/SKILL.md index c5d93a5d2..208b7422d 100644 --- a/.gemini/skills/critique/SKILL.md +++ b/.gemini/skills/critique/SKILL.md @@ -7,7 +7,7 @@ description: Evaluate design from a UX perspective, assessing visual hierarchy, ### Step 1: Preparation -Invoke /frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -25,7 +25,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -143,7 +143,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `GEMINI.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `GEMINI.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/.gemini/skills/critique/reference/personas.md b/.gemini/skills/critique/reference/personas.md index 80b38a939..cf6da3c50 100644 --- a/.gemini/skills/critique/reference/personas.md +++ b/.gemini/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `GEMINI.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `GEMINI.md` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/.gemini/skills/delight/SKILL.md b/.gemini/skills/delight/SKILL.md index d3d76c3ae..71b990589 100644 --- a/.gemini/skills/delight/SKILL.md +++ b/.gemini/skills/delight/SKILL.md @@ -7,7 +7,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/.gemini/skills/distill/SKILL.md b/.gemini/skills/distill/SKILL.md index 05b49d392..8ee7f4d38 100644 --- a/.gemini/skills/distill/SKILL.md +++ b/.gemini/skills/distill/SKILL.md @@ -7,7 +7,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.gemini/skills/frontend-design/SKILL.md b/.gemini/skills/frontend-design/SKILL.md index 120010041..459cf0542 100644 --- a/.gemini/skills/frontend-design/SKILL.md +++ b/.gemini/skills/frontend-design/SKILL.md @@ -1,146 +1,12 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. +description: DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead. --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `/impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `/impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `/impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run /teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: Gemini is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file +Do NOT attempt any design work from this skill. Redirect to `/impeccable` instead. \ No newline at end of file diff --git a/.gemini/skills/impeccable/SKILL.md b/.gemini/skills/impeccable/SKILL.md new file mode 100644 index 000000000..357830bac --- /dev/null +++ b/.gemini/skills/impeccable/SKILL.md @@ -0,0 +1,216 @@ +--- +name: impeccable +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: Gemini is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to GEMINI.md. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/.gemini/skills/frontend-design/reference/color-and-contrast.md b/.gemini/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from .gemini/skills/frontend-design/reference/color-and-contrast.md rename to .gemini/skills/impeccable/reference/color-and-contrast.md diff --git a/.gemini/skills/frontend-design/reference/interaction-design.md b/.gemini/skills/impeccable/reference/interaction-design.md similarity index 100% rename from .gemini/skills/frontend-design/reference/interaction-design.md rename to .gemini/skills/impeccable/reference/interaction-design.md diff --git a/.gemini/skills/frontend-design/reference/motion-design.md b/.gemini/skills/impeccable/reference/motion-design.md similarity index 100% rename from .gemini/skills/frontend-design/reference/motion-design.md rename to .gemini/skills/impeccable/reference/motion-design.md diff --git a/.gemini/skills/frontend-design/reference/responsive-design.md b/.gemini/skills/impeccable/reference/responsive-design.md similarity index 100% rename from .gemini/skills/frontend-design/reference/responsive-design.md rename to .gemini/skills/impeccable/reference/responsive-design.md diff --git a/.gemini/skills/frontend-design/reference/spatial-design.md b/.gemini/skills/impeccable/reference/spatial-design.md similarity index 100% rename from .gemini/skills/frontend-design/reference/spatial-design.md rename to .gemini/skills/impeccable/reference/spatial-design.md diff --git a/.gemini/skills/frontend-design/reference/typography.md b/.gemini/skills/impeccable/reference/typography.md similarity index 100% rename from .gemini/skills/frontend-design/reference/typography.md rename to .gemini/skills/impeccable/reference/typography.md diff --git a/.gemini/skills/frontend-design/reference/ux-writing.md b/.gemini/skills/impeccable/reference/ux-writing.md similarity index 100% rename from .gemini/skills/frontend-design/reference/ux-writing.md rename to .gemini/skills/impeccable/reference/ux-writing.md diff --git a/.gemini/skills/normalize/SKILL.md b/.gemini/skills/normalize/SKILL.md index 260a96fec..c3e3c6256 100644 --- a/.gemini/skills/normalize/SKILL.md +++ b/.gemini/skills/normalize/SKILL.md @@ -7,7 +7,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.gemini/skills/onboard/SKILL.md b/.gemini/skills/onboard/SKILL.md index 2e9f7773d..cd529ecb9 100644 --- a/.gemini/skills/onboard/SKILL.md +++ b/.gemini/skills/onboard/SKILL.md @@ -5,7 +5,7 @@ description: Designs and improves onboarding flows, empty states, and first-run ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/.gemini/skills/overdrive/SKILL.md b/.gemini/skills/overdrive/SKILL.md index f890ceae4..77c16f661 100644 --- a/.gemini/skills/overdrive/SKILL.md +++ b/.gemini/skills/overdrive/SKILL.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/.gemini/skills/polish/SKILL.md b/.gemini/skills/polish/SKILL.md index fe7c63210..53c97fec8 100644 --- a/.gemini/skills/polish/SKILL.md +++ b/.gemini/skills/polish/SKILL.md @@ -5,7 +5,7 @@ description: Performs a final quality pass fixing alignment, spacing, consistenc ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/.gemini/skills/quieter/SKILL.md b/.gemini/skills/quieter/SKILL.md index 22375f005..0fad7086c 100644 --- a/.gemini/skills/quieter/SKILL.md +++ b/.gemini/skills/quieter/SKILL.md @@ -7,7 +7,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.gemini/skills/teach-impeccable/SKILL.md b/.gemini/skills/teach-impeccable/SKILL.md index dc342c41a..0847a769f 100644 --- a/.gemini/skills/teach-impeccable/SKILL.md +++ b/.gemini/skills/teach-impeccable/SKILL.md @@ -1,70 +1,10 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill. --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `/impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to GEMINI.md. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file +> The `/teach-impeccable` command has been renamed to `/impeccable teach`. Please use that instead. \ No newline at end of file diff --git a/.gemini/skills/typeset/SKILL.md b/.gemini/skills/typeset/SKILL.md index 2acf08b3e..d534c5002 100644 --- a/.gemini/skills/typeset/SKILL.md +++ b/.gemini/skills/typeset/SKILL.md @@ -7,7 +7,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -44,7 +44,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/.kiro/skills/adapt/SKILL.md b/.kiro/skills/adapt/SKILL.md index 2b30e16f4..a6de081bf 100644 --- a/.kiro/skills/adapt/SKILL.md +++ b/.kiro/skills/adapt/SKILL.md @@ -7,7 +7,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/.kiro/skills/animate/SKILL.md b/.kiro/skills/animate/SKILL.md index f22c210db..21cb29942 100644 --- a/.kiro/skills/animate/SKILL.md +++ b/.kiro/skills/animate/SKILL.md @@ -7,7 +7,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: performance constraints. --- diff --git a/.kiro/skills/arrange/SKILL.md b/.kiro/skills/arrange/SKILL.md index 1d3a6beb2..f80a260e9 100644 --- a/.kiro/skills/arrange/SKILL.md +++ b/.kiro/skills/arrange/SKILL.md @@ -7,7 +7,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -44,7 +44,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/.kiro/skills/audit/SKILL.md b/.kiro/skills/audit/SKILL.md index 6dc747d60..1bcc446e2 100644 --- a/.kiro/skills/audit/SKILL.md +++ b/.kiro/skills/audit/SKILL.md @@ -5,7 +5,7 @@ description: Run technical quality checks across accessibility, performance, the ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -63,7 +63,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/.kiro/skills/bolder/SKILL.md b/.kiro/skills/bolder/SKILL.md index a43c8003d..281f9d2a4 100644 --- a/.kiro/skills/bolder/SKILL.md +++ b/.kiro/skills/bolder/SKILL.md @@ -7,7 +7,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -33,7 +33,7 @@ If any of these are unclear from the codebase, ask the user directly to clarify **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -51,7 +51,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/.kiro/skills/clarify/SKILL.md b/.kiro/skills/clarify/SKILL.md index 462a515fa..23e6b330c 100644 --- a/.kiro/skills/clarify/SKILL.md +++ b/.kiro/skills/clarify/SKILL.md @@ -7,7 +7,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/.kiro/skills/colorize/SKILL.md b/.kiro/skills/colorize/SKILL.md index 39cabdaf3..7dea7b6c4 100644 --- a/.kiro/skills/colorize/SKILL.md +++ b/.kiro/skills/colorize/SKILL.md @@ -7,7 +7,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: existing brand colors. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/.kiro/skills/critique/SKILL.md b/.kiro/skills/critique/SKILL.md index 687a74914..9fea1854e 100644 --- a/.kiro/skills/critique/SKILL.md +++ b/.kiro/skills/critique/SKILL.md @@ -7,7 +7,7 @@ description: Evaluate design from a UX perspective, assessing visual hierarchy, ### Step 1: Preparation -Invoke /frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -25,7 +25,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -143,7 +143,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `.kiro/settings.json` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `.kiro/settings.json` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/.kiro/skills/critique/reference/personas.md b/.kiro/skills/critique/reference/personas.md index 615d30d74..025ad90cd 100644 --- a/.kiro/skills/critique/reference/personas.md +++ b/.kiro/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `.kiro/settings.json` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `.kiro/settings.json` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/.kiro/skills/delight/SKILL.md b/.kiro/skills/delight/SKILL.md index d3d76c3ae..71b990589 100644 --- a/.kiro/skills/delight/SKILL.md +++ b/.kiro/skills/delight/SKILL.md @@ -7,7 +7,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/.kiro/skills/distill/SKILL.md b/.kiro/skills/distill/SKILL.md index 05b49d392..8ee7f4d38 100644 --- a/.kiro/skills/distill/SKILL.md +++ b/.kiro/skills/distill/SKILL.md @@ -7,7 +7,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.kiro/skills/frontend-design/SKILL.md b/.kiro/skills/frontend-design/SKILL.md index f7ad80468..459cf0542 100644 --- a/.kiro/skills/frontend-design/SKILL.md +++ b/.kiro/skills/frontend-design/SKILL.md @@ -1,147 +1,12 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. -license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +description: DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead. --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `/impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `/impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `/impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run /teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: Claude is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file +Do NOT attempt any design work from this skill. Redirect to `/impeccable` instead. \ No newline at end of file diff --git a/.kiro/skills/impeccable/SKILL.md b/.kiro/skills/impeccable/SKILL.md new file mode 100644 index 000000000..f1a551fbb --- /dev/null +++ b/.kiro/skills/impeccable/SKILL.md @@ -0,0 +1,217 @@ +--- +name: impeccable +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: Claude is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .kiro/settings.json. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/.kiro/skills/frontend-design/reference/color-and-contrast.md b/.kiro/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from .kiro/skills/frontend-design/reference/color-and-contrast.md rename to .kiro/skills/impeccable/reference/color-and-contrast.md diff --git a/.kiro/skills/frontend-design/reference/interaction-design.md b/.kiro/skills/impeccable/reference/interaction-design.md similarity index 100% rename from .kiro/skills/frontend-design/reference/interaction-design.md rename to .kiro/skills/impeccable/reference/interaction-design.md diff --git a/.kiro/skills/frontend-design/reference/motion-design.md b/.kiro/skills/impeccable/reference/motion-design.md similarity index 100% rename from .kiro/skills/frontend-design/reference/motion-design.md rename to .kiro/skills/impeccable/reference/motion-design.md diff --git a/.kiro/skills/frontend-design/reference/responsive-design.md b/.kiro/skills/impeccable/reference/responsive-design.md similarity index 100% rename from .kiro/skills/frontend-design/reference/responsive-design.md rename to .kiro/skills/impeccable/reference/responsive-design.md diff --git a/.kiro/skills/frontend-design/reference/spatial-design.md b/.kiro/skills/impeccable/reference/spatial-design.md similarity index 100% rename from .kiro/skills/frontend-design/reference/spatial-design.md rename to .kiro/skills/impeccable/reference/spatial-design.md diff --git a/.kiro/skills/frontend-design/reference/typography.md b/.kiro/skills/impeccable/reference/typography.md similarity index 100% rename from .kiro/skills/frontend-design/reference/typography.md rename to .kiro/skills/impeccable/reference/typography.md diff --git a/.kiro/skills/frontend-design/reference/ux-writing.md b/.kiro/skills/impeccable/reference/ux-writing.md similarity index 100% rename from .kiro/skills/frontend-design/reference/ux-writing.md rename to .kiro/skills/impeccable/reference/ux-writing.md diff --git a/.kiro/skills/normalize/SKILL.md b/.kiro/skills/normalize/SKILL.md index 260a96fec..c3e3c6256 100644 --- a/.kiro/skills/normalize/SKILL.md +++ b/.kiro/skills/normalize/SKILL.md @@ -7,7 +7,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.kiro/skills/onboard/SKILL.md b/.kiro/skills/onboard/SKILL.md index 2e9f7773d..cd529ecb9 100644 --- a/.kiro/skills/onboard/SKILL.md +++ b/.kiro/skills/onboard/SKILL.md @@ -5,7 +5,7 @@ description: Designs and improves onboarding flows, empty states, and first-run ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/.kiro/skills/overdrive/SKILL.md b/.kiro/skills/overdrive/SKILL.md index f890ceae4..77c16f661 100644 --- a/.kiro/skills/overdrive/SKILL.md +++ b/.kiro/skills/overdrive/SKILL.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/.kiro/skills/polish/SKILL.md b/.kiro/skills/polish/SKILL.md index fe7c63210..53c97fec8 100644 --- a/.kiro/skills/polish/SKILL.md +++ b/.kiro/skills/polish/SKILL.md @@ -5,7 +5,7 @@ description: Performs a final quality pass fixing alignment, spacing, consistenc ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/.kiro/skills/quieter/SKILL.md b/.kiro/skills/quieter/SKILL.md index 22375f005..0fad7086c 100644 --- a/.kiro/skills/quieter/SKILL.md +++ b/.kiro/skills/quieter/SKILL.md @@ -7,7 +7,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.kiro/skills/teach-impeccable/SKILL.md b/.kiro/skills/teach-impeccable/SKILL.md index 72d807056..0847a769f 100644 --- a/.kiro/skills/teach-impeccable/SKILL.md +++ b/.kiro/skills/teach-impeccable/SKILL.md @@ -1,70 +1,10 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill. --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `/impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .kiro/settings.json. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file +> The `/teach-impeccable` command has been renamed to `/impeccable teach`. Please use that instead. \ No newline at end of file diff --git a/.kiro/skills/typeset/SKILL.md b/.kiro/skills/typeset/SKILL.md index 2acf08b3e..d534c5002 100644 --- a/.kiro/skills/typeset/SKILL.md +++ b/.kiro/skills/typeset/SKILL.md @@ -7,7 +7,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -44,7 +44,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/.opencode/skills/adapt/SKILL.md b/.opencode/skills/adapt/SKILL.md index 165c66dcc..537c15b32 100644 --- a/.opencode/skills/adapt/SKILL.md +++ b/.opencode/skills/adapt/SKILL.md @@ -9,7 +9,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/.opencode/skills/animate/SKILL.md b/.opencode/skills/animate/SKILL.md index 479f9916a..dc3e49a2f 100644 --- a/.opencode/skills/animate/SKILL.md +++ b/.opencode/skills/animate/SKILL.md @@ -9,7 +9,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: performance constraints. --- diff --git a/.opencode/skills/arrange/SKILL.md b/.opencode/skills/arrange/SKILL.md index ce4cf3ad6..d63c1aab0 100644 --- a/.opencode/skills/arrange/SKILL.md +++ b/.opencode/skills/arrange/SKILL.md @@ -9,7 +9,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/.opencode/skills/audit/SKILL.md b/.opencode/skills/audit/SKILL.md index 1debe043e..4d54dca12 100644 --- a/.opencode/skills/audit/SKILL.md +++ b/.opencode/skills/audit/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[area (feature, page, component...)]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -65,7 +65,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/.opencode/skills/bolder/SKILL.md b/.opencode/skills/bolder/SKILL.md index b4b014735..ee3e93384 100644 --- a/.opencode/skills/bolder/SKILL.md +++ b/.opencode/skills/bolder/SKILL.md @@ -9,7 +9,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -35,7 +35,7 @@ If any of these are unclear from the codebase, STOP and call the `question` tool **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -53,7 +53,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/.opencode/skills/clarify/SKILL.md b/.opencode/skills/clarify/SKILL.md index 4db9228d6..0ee5eb997 100644 --- a/.opencode/skills/clarify/SKILL.md +++ b/.opencode/skills/clarify/SKILL.md @@ -9,7 +9,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/.opencode/skills/colorize/SKILL.md b/.opencode/skills/colorize/SKILL.md index c77cedb4d..43d4cfac3 100644 --- a/.opencode/skills/colorize/SKILL.md +++ b/.opencode/skills/colorize/SKILL.md @@ -9,7 +9,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: existing brand colors. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/.opencode/skills/critique/SKILL.md b/.opencode/skills/critique/SKILL.md index 9816bb9e7..0f2baab12 100644 --- a/.opencode/skills/critique/SKILL.md +++ b/.opencode/skills/critique/SKILL.md @@ -14,7 +14,7 @@ allowed-tools: ### Step 1: Preparation -Invoke /frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -32,7 +32,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -150,7 +150,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/.opencode/skills/critique/reference/personas.md b/.opencode/skills/critique/reference/personas.md index 2d0f9cbf3..5e91eb651 100644 --- a/.opencode/skills/critique/reference/personas.md +++ b/.opencode/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `AGENTS.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `AGENTS.md` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/.opencode/skills/delight/SKILL.md b/.opencode/skills/delight/SKILL.md index 72a683bcc..459e9a622 100644 --- a/.opencode/skills/delight/SKILL.md +++ b/.opencode/skills/delight/SKILL.md @@ -9,7 +9,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/.opencode/skills/distill/SKILL.md b/.opencode/skills/distill/SKILL.md index 6c6ecbf3c..900d7afbb 100644 --- a/.opencode/skills/distill/SKILL.md +++ b/.opencode/skills/distill/SKILL.md @@ -9,7 +9,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.opencode/skills/frontend-design/SKILL.md b/.opencode/skills/frontend-design/SKILL.md index f7ad80468..459cf0542 100644 --- a/.opencode/skills/frontend-design/SKILL.md +++ b/.opencode/skills/frontend-design/SKILL.md @@ -1,147 +1,12 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. -license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +description: DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead. --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `/impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `/impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `/impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run /teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: Claude is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file +Do NOT attempt any design work from this skill. Redirect to `/impeccable` instead. \ No newline at end of file diff --git a/.opencode/skills/impeccable/SKILL.md b/.opencode/skills/impeccable/SKILL.md new file mode 100644 index 000000000..08bec3905 --- /dev/null +++ b/.opencode/skills/impeccable/SKILL.md @@ -0,0 +1,219 @@ +--- +name: impeccable +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +user-invocable: true +argument-hint: "[teach]" +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: Claude is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +STOP and call the `question` tool to clarify. Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then STOP and call the `question` tool to clarify. whether they'd also like the Design Context appended to AGENTS.md. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/.opencode/skills/frontend-design/reference/color-and-contrast.md b/.opencode/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from .opencode/skills/frontend-design/reference/color-and-contrast.md rename to .opencode/skills/impeccable/reference/color-and-contrast.md diff --git a/.opencode/skills/frontend-design/reference/interaction-design.md b/.opencode/skills/impeccable/reference/interaction-design.md similarity index 100% rename from .opencode/skills/frontend-design/reference/interaction-design.md rename to .opencode/skills/impeccable/reference/interaction-design.md diff --git a/.opencode/skills/frontend-design/reference/motion-design.md b/.opencode/skills/impeccable/reference/motion-design.md similarity index 100% rename from .opencode/skills/frontend-design/reference/motion-design.md rename to .opencode/skills/impeccable/reference/motion-design.md diff --git a/.opencode/skills/frontend-design/reference/responsive-design.md b/.opencode/skills/impeccable/reference/responsive-design.md similarity index 100% rename from .opencode/skills/frontend-design/reference/responsive-design.md rename to .opencode/skills/impeccable/reference/responsive-design.md diff --git a/.opencode/skills/frontend-design/reference/spatial-design.md b/.opencode/skills/impeccable/reference/spatial-design.md similarity index 100% rename from .opencode/skills/frontend-design/reference/spatial-design.md rename to .opencode/skills/impeccable/reference/spatial-design.md diff --git a/.opencode/skills/frontend-design/reference/typography.md b/.opencode/skills/impeccable/reference/typography.md similarity index 100% rename from .opencode/skills/frontend-design/reference/typography.md rename to .opencode/skills/impeccable/reference/typography.md diff --git a/.opencode/skills/frontend-design/reference/ux-writing.md b/.opencode/skills/impeccable/reference/ux-writing.md similarity index 100% rename from .opencode/skills/frontend-design/reference/ux-writing.md rename to .opencode/skills/impeccable/reference/ux-writing.md diff --git a/.opencode/skills/normalize/SKILL.md b/.opencode/skills/normalize/SKILL.md index 4015c54a3..cbc512296 100644 --- a/.opencode/skills/normalize/SKILL.md +++ b/.opencode/skills/normalize/SKILL.md @@ -9,7 +9,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.opencode/skills/onboard/SKILL.md b/.opencode/skills/onboard/SKILL.md index 14666050b..01a1d2dd6 100644 --- a/.opencode/skills/onboard/SKILL.md +++ b/.opencode/skills/onboard/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/.opencode/skills/overdrive/SKILL.md b/.opencode/skills/overdrive/SKILL.md index 660b9afe7..076894244 100644 --- a/.opencode/skills/overdrive/SKILL.md +++ b/.opencode/skills/overdrive/SKILL.md @@ -16,7 +16,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/.opencode/skills/polish/SKILL.md b/.opencode/skills/polish/SKILL.md index fcaae6e88..1e8751a6a 100644 --- a/.opencode/skills/polish/SKILL.md +++ b/.opencode/skills/polish/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/.opencode/skills/quieter/SKILL.md b/.opencode/skills/quieter/SKILL.md index dcf4d3176..f52c2df9b 100644 --- a/.opencode/skills/quieter/SKILL.md +++ b/.opencode/skills/quieter/SKILL.md @@ -9,7 +9,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.opencode/skills/teach-impeccable/SKILL.md b/.opencode/skills/teach-impeccable/SKILL.md index 929496c0d..4f39eb5ae 100644 --- a/.opencode/skills/teach-impeccable/SKILL.md +++ b/.opencode/skills/teach-impeccable/SKILL.md @@ -1,71 +1,11 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill. user-invocable: true --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `/impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -STOP and call the `question` tool to clarify. Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then STOP and call the `question` tool to clarify. whether they'd also like the Design Context appended to AGENTS.md. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file +> The `/teach-impeccable` command has been renamed to `/impeccable teach`. Please use that instead. \ No newline at end of file diff --git a/.opencode/skills/typeset/SKILL.md b/.opencode/skills/typeset/SKILL.md index 139153a28..9d89fafad 100644 --- a/.opencode/skills/typeset/SKILL.md +++ b/.opencode/skills/typeset/SKILL.md @@ -9,7 +9,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/.pi/skills/adapt/SKILL.md b/.pi/skills/adapt/SKILL.md index 2b30e16f4..a6de081bf 100644 --- a/.pi/skills/adapt/SKILL.md +++ b/.pi/skills/adapt/SKILL.md @@ -7,7 +7,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/.pi/skills/animate/SKILL.md b/.pi/skills/animate/SKILL.md index f22c210db..21cb29942 100644 --- a/.pi/skills/animate/SKILL.md +++ b/.pi/skills/animate/SKILL.md @@ -7,7 +7,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: performance constraints. --- diff --git a/.pi/skills/arrange/SKILL.md b/.pi/skills/arrange/SKILL.md index 1d3a6beb2..f80a260e9 100644 --- a/.pi/skills/arrange/SKILL.md +++ b/.pi/skills/arrange/SKILL.md @@ -7,7 +7,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -44,7 +44,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/.pi/skills/audit/SKILL.md b/.pi/skills/audit/SKILL.md index 6dc747d60..1bcc446e2 100644 --- a/.pi/skills/audit/SKILL.md +++ b/.pi/skills/audit/SKILL.md @@ -5,7 +5,7 @@ description: Run technical quality checks across accessibility, performance, the ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -63,7 +63,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/.pi/skills/bolder/SKILL.md b/.pi/skills/bolder/SKILL.md index a43c8003d..281f9d2a4 100644 --- a/.pi/skills/bolder/SKILL.md +++ b/.pi/skills/bolder/SKILL.md @@ -7,7 +7,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -33,7 +33,7 @@ If any of these are unclear from the codebase, ask the user directly to clarify **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -51,7 +51,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/.pi/skills/clarify/SKILL.md b/.pi/skills/clarify/SKILL.md index 462a515fa..23e6b330c 100644 --- a/.pi/skills/clarify/SKILL.md +++ b/.pi/skills/clarify/SKILL.md @@ -7,7 +7,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/.pi/skills/colorize/SKILL.md b/.pi/skills/colorize/SKILL.md index 39cabdaf3..7dea7b6c4 100644 --- a/.pi/skills/colorize/SKILL.md +++ b/.pi/skills/colorize/SKILL.md @@ -7,7 +7,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: existing brand colors. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/.pi/skills/critique/SKILL.md b/.pi/skills/critique/SKILL.md index 6a030abc7..459d29a82 100644 --- a/.pi/skills/critique/SKILL.md +++ b/.pi/skills/critique/SKILL.md @@ -12,7 +12,7 @@ allowed-tools: ### Step 1: Preparation -Invoke /frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -30,7 +30,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -148,7 +148,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/.pi/skills/critique/reference/personas.md b/.pi/skills/critique/reference/personas.md index 2d0f9cbf3..5e91eb651 100644 --- a/.pi/skills/critique/reference/personas.md +++ b/.pi/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `AGENTS.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `AGENTS.md` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/.pi/skills/delight/SKILL.md b/.pi/skills/delight/SKILL.md index d3d76c3ae..71b990589 100644 --- a/.pi/skills/delight/SKILL.md +++ b/.pi/skills/delight/SKILL.md @@ -7,7 +7,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/.pi/skills/distill/SKILL.md b/.pi/skills/distill/SKILL.md index 05b49d392..8ee7f4d38 100644 --- a/.pi/skills/distill/SKILL.md +++ b/.pi/skills/distill/SKILL.md @@ -7,7 +7,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.pi/skills/frontend-design/SKILL.md b/.pi/skills/frontend-design/SKILL.md index dd7c5dd4c..459cf0542 100644 --- a/.pi/skills/frontend-design/SKILL.md +++ b/.pi/skills/frontend-design/SKILL.md @@ -1,147 +1,12 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. -license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +description: DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead. --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `/impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `/impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `/impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run /teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: the model is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file +Do NOT attempt any design work from this skill. Redirect to `/impeccable` instead. \ No newline at end of file diff --git a/.pi/skills/impeccable/SKILL.md b/.pi/skills/impeccable/SKILL.md new file mode 100644 index 000000000..700385390 --- /dev/null +++ b/.pi/skills/impeccable/SKILL.md @@ -0,0 +1,217 @@ +--- +name: impeccable +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: the model is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to AGENTS.md. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/.pi/skills/frontend-design/reference/color-and-contrast.md b/.pi/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from .pi/skills/frontend-design/reference/color-and-contrast.md rename to .pi/skills/impeccable/reference/color-and-contrast.md diff --git a/.pi/skills/frontend-design/reference/interaction-design.md b/.pi/skills/impeccable/reference/interaction-design.md similarity index 100% rename from .pi/skills/frontend-design/reference/interaction-design.md rename to .pi/skills/impeccable/reference/interaction-design.md diff --git a/.pi/skills/frontend-design/reference/motion-design.md b/.pi/skills/impeccable/reference/motion-design.md similarity index 100% rename from .pi/skills/frontend-design/reference/motion-design.md rename to .pi/skills/impeccable/reference/motion-design.md diff --git a/.pi/skills/frontend-design/reference/responsive-design.md b/.pi/skills/impeccable/reference/responsive-design.md similarity index 100% rename from .pi/skills/frontend-design/reference/responsive-design.md rename to .pi/skills/impeccable/reference/responsive-design.md diff --git a/.pi/skills/frontend-design/reference/spatial-design.md b/.pi/skills/impeccable/reference/spatial-design.md similarity index 100% rename from .pi/skills/frontend-design/reference/spatial-design.md rename to .pi/skills/impeccable/reference/spatial-design.md diff --git a/.pi/skills/frontend-design/reference/typography.md b/.pi/skills/impeccable/reference/typography.md similarity index 100% rename from .pi/skills/frontend-design/reference/typography.md rename to .pi/skills/impeccable/reference/typography.md diff --git a/.pi/skills/frontend-design/reference/ux-writing.md b/.pi/skills/impeccable/reference/ux-writing.md similarity index 100% rename from .pi/skills/frontend-design/reference/ux-writing.md rename to .pi/skills/impeccable/reference/ux-writing.md diff --git a/.pi/skills/normalize/SKILL.md b/.pi/skills/normalize/SKILL.md index 260a96fec..c3e3c6256 100644 --- a/.pi/skills/normalize/SKILL.md +++ b/.pi/skills/normalize/SKILL.md @@ -7,7 +7,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.pi/skills/onboard/SKILL.md b/.pi/skills/onboard/SKILL.md index 2e9f7773d..cd529ecb9 100644 --- a/.pi/skills/onboard/SKILL.md +++ b/.pi/skills/onboard/SKILL.md @@ -5,7 +5,7 @@ description: Designs and improves onboarding flows, empty states, and first-run ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/.pi/skills/overdrive/SKILL.md b/.pi/skills/overdrive/SKILL.md index f890ceae4..77c16f661 100644 --- a/.pi/skills/overdrive/SKILL.md +++ b/.pi/skills/overdrive/SKILL.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/.pi/skills/polish/SKILL.md b/.pi/skills/polish/SKILL.md index fe7c63210..53c97fec8 100644 --- a/.pi/skills/polish/SKILL.md +++ b/.pi/skills/polish/SKILL.md @@ -5,7 +5,7 @@ description: Performs a final quality pass fixing alignment, spacing, consistenc ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/.pi/skills/quieter/SKILL.md b/.pi/skills/quieter/SKILL.md index 22375f005..0fad7086c 100644 --- a/.pi/skills/quieter/SKILL.md +++ b/.pi/skills/quieter/SKILL.md @@ -7,7 +7,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.pi/skills/teach-impeccable/SKILL.md b/.pi/skills/teach-impeccable/SKILL.md index 5267bf599..0847a769f 100644 --- a/.pi/skills/teach-impeccable/SKILL.md +++ b/.pi/skills/teach-impeccable/SKILL.md @@ -1,70 +1,10 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill. --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `/impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to AGENTS.md. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file +> The `/teach-impeccable` command has been renamed to `/impeccable teach`. Please use that instead. \ No newline at end of file diff --git a/.pi/skills/typeset/SKILL.md b/.pi/skills/typeset/SKILL.md index 2acf08b3e..d534c5002 100644 --- a/.pi/skills/typeset/SKILL.md +++ b/.pi/skills/typeset/SKILL.md @@ -7,7 +7,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -44,7 +44,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/.trae-cn/skills/adapt/SKILL.md b/.trae-cn/skills/adapt/SKILL.md index 165c66dcc..537c15b32 100644 --- a/.trae-cn/skills/adapt/SKILL.md +++ b/.trae-cn/skills/adapt/SKILL.md @@ -9,7 +9,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/.trae-cn/skills/animate/SKILL.md b/.trae-cn/skills/animate/SKILL.md index 3d006d15e..a28332e96 100644 --- a/.trae-cn/skills/animate/SKILL.md +++ b/.trae-cn/skills/animate/SKILL.md @@ -9,7 +9,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: performance constraints. --- diff --git a/.trae-cn/skills/arrange/SKILL.md b/.trae-cn/skills/arrange/SKILL.md index ce4cf3ad6..d63c1aab0 100644 --- a/.trae-cn/skills/arrange/SKILL.md +++ b/.trae-cn/skills/arrange/SKILL.md @@ -9,7 +9,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/.trae-cn/skills/audit/SKILL.md b/.trae-cn/skills/audit/SKILL.md index 1debe043e..4d54dca12 100644 --- a/.trae-cn/skills/audit/SKILL.md +++ b/.trae-cn/skills/audit/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[area (feature, page, component...)]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -65,7 +65,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/.trae-cn/skills/bolder/SKILL.md b/.trae-cn/skills/bolder/SKILL.md index 0b03f025f..94c6dc8f2 100644 --- a/.trae-cn/skills/bolder/SKILL.md +++ b/.trae-cn/skills/bolder/SKILL.md @@ -9,7 +9,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -35,7 +35,7 @@ If any of these are unclear from the codebase, ask the user directly to clarify **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -53,7 +53,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/.trae-cn/skills/clarify/SKILL.md b/.trae-cn/skills/clarify/SKILL.md index 4db9228d6..0ee5eb997 100644 --- a/.trae-cn/skills/clarify/SKILL.md +++ b/.trae-cn/skills/clarify/SKILL.md @@ -9,7 +9,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/.trae-cn/skills/colorize/SKILL.md b/.trae-cn/skills/colorize/SKILL.md index 0b092ac08..726dfaca0 100644 --- a/.trae-cn/skills/colorize/SKILL.md +++ b/.trae-cn/skills/colorize/SKILL.md @@ -9,7 +9,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: existing brand colors. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/.trae-cn/skills/critique/SKILL.md b/.trae-cn/skills/critique/SKILL.md index 7c3e40432..223f4c44e 100644 --- a/.trae-cn/skills/critique/SKILL.md +++ b/.trae-cn/skills/critique/SKILL.md @@ -9,7 +9,7 @@ argument-hint: "[area (feature, page, component...)]" ### Step 1: Preparation -Invoke /frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -27,7 +27,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -145,7 +145,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `RULES.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `RULES.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/.trae-cn/skills/critique/reference/personas.md b/.trae-cn/skills/critique/reference/personas.md index 6325e2839..261eea330 100644 --- a/.trae-cn/skills/critique/reference/personas.md +++ b/.trae-cn/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `RULES.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `RULES.md` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/.trae-cn/skills/delight/SKILL.md b/.trae-cn/skills/delight/SKILL.md index fe39492d7..161a4b2b4 100644 --- a/.trae-cn/skills/delight/SKILL.md +++ b/.trae-cn/skills/delight/SKILL.md @@ -9,7 +9,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/.trae-cn/skills/distill/SKILL.md b/.trae-cn/skills/distill/SKILL.md index fd2a8e47f..fbe16f3e8 100644 --- a/.trae-cn/skills/distill/SKILL.md +++ b/.trae-cn/skills/distill/SKILL.md @@ -9,7 +9,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.trae-cn/skills/frontend-design/SKILL.md b/.trae-cn/skills/frontend-design/SKILL.md index dd7c5dd4c..459cf0542 100644 --- a/.trae-cn/skills/frontend-design/SKILL.md +++ b/.trae-cn/skills/frontend-design/SKILL.md @@ -1,147 +1,12 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. -license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +description: DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead. --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `/impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `/impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `/impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run /teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: the model is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file +Do NOT attempt any design work from this skill. Redirect to `/impeccable` instead. \ No newline at end of file diff --git a/.trae-cn/skills/impeccable/SKILL.md b/.trae-cn/skills/impeccable/SKILL.md new file mode 100644 index 000000000..2eae4e2f6 --- /dev/null +++ b/.trae-cn/skills/impeccable/SKILL.md @@ -0,0 +1,219 @@ +--- +name: impeccable +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +user-invocable: true +argument-hint: "[teach]" +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: the model is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to RULES.md. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/.trae-cn/skills/frontend-design/reference/color-and-contrast.md b/.trae-cn/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from .trae-cn/skills/frontend-design/reference/color-and-contrast.md rename to .trae-cn/skills/impeccable/reference/color-and-contrast.md diff --git a/.trae-cn/skills/frontend-design/reference/interaction-design.md b/.trae-cn/skills/impeccable/reference/interaction-design.md similarity index 100% rename from .trae-cn/skills/frontend-design/reference/interaction-design.md rename to .trae-cn/skills/impeccable/reference/interaction-design.md diff --git a/.trae-cn/skills/frontend-design/reference/motion-design.md b/.trae-cn/skills/impeccable/reference/motion-design.md similarity index 100% rename from .trae-cn/skills/frontend-design/reference/motion-design.md rename to .trae-cn/skills/impeccable/reference/motion-design.md diff --git a/.trae-cn/skills/frontend-design/reference/responsive-design.md b/.trae-cn/skills/impeccable/reference/responsive-design.md similarity index 100% rename from .trae-cn/skills/frontend-design/reference/responsive-design.md rename to .trae-cn/skills/impeccable/reference/responsive-design.md diff --git a/.trae-cn/skills/frontend-design/reference/spatial-design.md b/.trae-cn/skills/impeccable/reference/spatial-design.md similarity index 100% rename from .trae-cn/skills/frontend-design/reference/spatial-design.md rename to .trae-cn/skills/impeccable/reference/spatial-design.md diff --git a/.trae-cn/skills/frontend-design/reference/typography.md b/.trae-cn/skills/impeccable/reference/typography.md similarity index 100% rename from .trae-cn/skills/frontend-design/reference/typography.md rename to .trae-cn/skills/impeccable/reference/typography.md diff --git a/.trae-cn/skills/frontend-design/reference/ux-writing.md b/.trae-cn/skills/impeccable/reference/ux-writing.md similarity index 100% rename from .trae-cn/skills/frontend-design/reference/ux-writing.md rename to .trae-cn/skills/impeccable/reference/ux-writing.md diff --git a/.trae-cn/skills/normalize/SKILL.md b/.trae-cn/skills/normalize/SKILL.md index 4015c54a3..cbc512296 100644 --- a/.trae-cn/skills/normalize/SKILL.md +++ b/.trae-cn/skills/normalize/SKILL.md @@ -9,7 +9,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.trae-cn/skills/onboard/SKILL.md b/.trae-cn/skills/onboard/SKILL.md index 14666050b..01a1d2dd6 100644 --- a/.trae-cn/skills/onboard/SKILL.md +++ b/.trae-cn/skills/onboard/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/.trae-cn/skills/overdrive/SKILL.md b/.trae-cn/skills/overdrive/SKILL.md index fd9199ec6..a389e6346 100644 --- a/.trae-cn/skills/overdrive/SKILL.md +++ b/.trae-cn/skills/overdrive/SKILL.md @@ -16,7 +16,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/.trae-cn/skills/polish/SKILL.md b/.trae-cn/skills/polish/SKILL.md index fcaae6e88..1e8751a6a 100644 --- a/.trae-cn/skills/polish/SKILL.md +++ b/.trae-cn/skills/polish/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/.trae-cn/skills/quieter/SKILL.md b/.trae-cn/skills/quieter/SKILL.md index 555ca446e..314f574be 100644 --- a/.trae-cn/skills/quieter/SKILL.md +++ b/.trae-cn/skills/quieter/SKILL.md @@ -9,7 +9,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.trae-cn/skills/teach-impeccable/SKILL.md b/.trae-cn/skills/teach-impeccable/SKILL.md index 8d396d08a..4f39eb5ae 100644 --- a/.trae-cn/skills/teach-impeccable/SKILL.md +++ b/.trae-cn/skills/teach-impeccable/SKILL.md @@ -1,71 +1,11 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill. user-invocable: true --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `/impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to RULES.md. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file +> The `/teach-impeccable` command has been renamed to `/impeccable teach`. Please use that instead. \ No newline at end of file diff --git a/.trae-cn/skills/typeset/SKILL.md b/.trae-cn/skills/typeset/SKILL.md index 139153a28..9d89fafad 100644 --- a/.trae-cn/skills/typeset/SKILL.md +++ b/.trae-cn/skills/typeset/SKILL.md @@ -9,7 +9,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/.trae/skills/adapt/SKILL.md b/.trae/skills/adapt/SKILL.md index 165c66dcc..537c15b32 100644 --- a/.trae/skills/adapt/SKILL.md +++ b/.trae/skills/adapt/SKILL.md @@ -9,7 +9,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/.trae/skills/animate/SKILL.md b/.trae/skills/animate/SKILL.md index 3d006d15e..a28332e96 100644 --- a/.trae/skills/animate/SKILL.md +++ b/.trae/skills/animate/SKILL.md @@ -9,7 +9,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: performance constraints. --- diff --git a/.trae/skills/arrange/SKILL.md b/.trae/skills/arrange/SKILL.md index ce4cf3ad6..d63c1aab0 100644 --- a/.trae/skills/arrange/SKILL.md +++ b/.trae/skills/arrange/SKILL.md @@ -9,7 +9,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/.trae/skills/audit/SKILL.md b/.trae/skills/audit/SKILL.md index 1debe043e..4d54dca12 100644 --- a/.trae/skills/audit/SKILL.md +++ b/.trae/skills/audit/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[area (feature, page, component...)]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -65,7 +65,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/.trae/skills/bolder/SKILL.md b/.trae/skills/bolder/SKILL.md index 0b03f025f..94c6dc8f2 100644 --- a/.trae/skills/bolder/SKILL.md +++ b/.trae/skills/bolder/SKILL.md @@ -9,7 +9,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -35,7 +35,7 @@ If any of these are unclear from the codebase, ask the user directly to clarify **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -53,7 +53,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/.trae/skills/clarify/SKILL.md b/.trae/skills/clarify/SKILL.md index 4db9228d6..0ee5eb997 100644 --- a/.trae/skills/clarify/SKILL.md +++ b/.trae/skills/clarify/SKILL.md @@ -9,7 +9,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/.trae/skills/colorize/SKILL.md b/.trae/skills/colorize/SKILL.md index 0b092ac08..726dfaca0 100644 --- a/.trae/skills/colorize/SKILL.md +++ b/.trae/skills/colorize/SKILL.md @@ -9,7 +9,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: existing brand colors. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/.trae/skills/critique/SKILL.md b/.trae/skills/critique/SKILL.md index 7c3e40432..223f4c44e 100644 --- a/.trae/skills/critique/SKILL.md +++ b/.trae/skills/critique/SKILL.md @@ -9,7 +9,7 @@ argument-hint: "[area (feature, page, component...)]" ### Step 1: Preparation -Invoke /frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -27,7 +27,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -145,7 +145,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `RULES.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `RULES.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/.trae/skills/critique/reference/personas.md b/.trae/skills/critique/reference/personas.md index 6325e2839..261eea330 100644 --- a/.trae/skills/critique/reference/personas.md +++ b/.trae/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `RULES.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `RULES.md` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/.trae/skills/delight/SKILL.md b/.trae/skills/delight/SKILL.md index fe39492d7..161a4b2b4 100644 --- a/.trae/skills/delight/SKILL.md +++ b/.trae/skills/delight/SKILL.md @@ -9,7 +9,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/.trae/skills/distill/SKILL.md b/.trae/skills/distill/SKILL.md index fd2a8e47f..fbe16f3e8 100644 --- a/.trae/skills/distill/SKILL.md +++ b/.trae/skills/distill/SKILL.md @@ -9,7 +9,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.trae/skills/frontend-design/SKILL.md b/.trae/skills/frontend-design/SKILL.md index dd7c5dd4c..459cf0542 100644 --- a/.trae/skills/frontend-design/SKILL.md +++ b/.trae/skills/frontend-design/SKILL.md @@ -1,147 +1,12 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. -license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +description: DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead. --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `/impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `/impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `/impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run /teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: the model is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file +Do NOT attempt any design work from this skill. Redirect to `/impeccable` instead. \ No newline at end of file diff --git a/.trae/skills/impeccable/SKILL.md b/.trae/skills/impeccable/SKILL.md new file mode 100644 index 000000000..2eae4e2f6 --- /dev/null +++ b/.trae/skills/impeccable/SKILL.md @@ -0,0 +1,219 @@ +--- +name: impeccable +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +user-invocable: true +argument-hint: "[teach]" +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: the model is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to RULES.md. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/.trae/skills/frontend-design/reference/color-and-contrast.md b/.trae/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from .trae/skills/frontend-design/reference/color-and-contrast.md rename to .trae/skills/impeccable/reference/color-and-contrast.md diff --git a/.trae/skills/frontend-design/reference/interaction-design.md b/.trae/skills/impeccable/reference/interaction-design.md similarity index 100% rename from .trae/skills/frontend-design/reference/interaction-design.md rename to .trae/skills/impeccable/reference/interaction-design.md diff --git a/.trae/skills/frontend-design/reference/motion-design.md b/.trae/skills/impeccable/reference/motion-design.md similarity index 100% rename from .trae/skills/frontend-design/reference/motion-design.md rename to .trae/skills/impeccable/reference/motion-design.md diff --git a/.trae/skills/frontend-design/reference/responsive-design.md b/.trae/skills/impeccable/reference/responsive-design.md similarity index 100% rename from .trae/skills/frontend-design/reference/responsive-design.md rename to .trae/skills/impeccable/reference/responsive-design.md diff --git a/.trae/skills/frontend-design/reference/spatial-design.md b/.trae/skills/impeccable/reference/spatial-design.md similarity index 100% rename from .trae/skills/frontend-design/reference/spatial-design.md rename to .trae/skills/impeccable/reference/spatial-design.md diff --git a/.trae/skills/frontend-design/reference/typography.md b/.trae/skills/impeccable/reference/typography.md similarity index 100% rename from .trae/skills/frontend-design/reference/typography.md rename to .trae/skills/impeccable/reference/typography.md diff --git a/.trae/skills/frontend-design/reference/ux-writing.md b/.trae/skills/impeccable/reference/ux-writing.md similarity index 100% rename from .trae/skills/frontend-design/reference/ux-writing.md rename to .trae/skills/impeccable/reference/ux-writing.md diff --git a/.trae/skills/normalize/SKILL.md b/.trae/skills/normalize/SKILL.md index 4015c54a3..cbc512296 100644 --- a/.trae/skills/normalize/SKILL.md +++ b/.trae/skills/normalize/SKILL.md @@ -9,7 +9,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.trae/skills/onboard/SKILL.md b/.trae/skills/onboard/SKILL.md index 14666050b..01a1d2dd6 100644 --- a/.trae/skills/onboard/SKILL.md +++ b/.trae/skills/onboard/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/.trae/skills/overdrive/SKILL.md b/.trae/skills/overdrive/SKILL.md index fd9199ec6..a389e6346 100644 --- a/.trae/skills/overdrive/SKILL.md +++ b/.trae/skills/overdrive/SKILL.md @@ -16,7 +16,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/.trae/skills/polish/SKILL.md b/.trae/skills/polish/SKILL.md index fcaae6e88..1e8751a6a 100644 --- a/.trae/skills/polish/SKILL.md +++ b/.trae/skills/polish/SKILL.md @@ -7,7 +7,7 @@ argument-hint: "[target]" ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/.trae/skills/quieter/SKILL.md b/.trae/skills/quieter/SKILL.md index 555ca446e..314f574be 100644 --- a/.trae/skills/quieter/SKILL.md +++ b/.trae/skills/quieter/SKILL.md @@ -9,7 +9,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- diff --git a/.trae/skills/teach-impeccable/SKILL.md b/.trae/skills/teach-impeccable/SKILL.md index 8d396d08a..4f39eb5ae 100644 --- a/.trae/skills/teach-impeccable/SKILL.md +++ b/.trae/skills/teach-impeccable/SKILL.md @@ -1,71 +1,11 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill. user-invocable: true --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `/impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to RULES.md. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file +> The `/teach-impeccable` command has been renamed to `/impeccable teach`. Please use that instead. \ No newline at end of file diff --git a/.trae/skills/typeset/SKILL.md b/.trae/skills/typeset/SKILL.md index 139153a28..9d89fafad 100644 --- a/.trae/skills/typeset/SKILL.md +++ b/.trae/skills/typeset/SKILL.md @@ -9,7 +9,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. +Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/AGENTS.md b/AGENTS.md index 60e29e45c..6252f0cb8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ impeccable/ │ ├── commands/ # Command definitions with frontmatter │ │ └── normalize.md │ └── skills/ # Skill definitions with frontmatter -│ └── frontend-design.md +│ └── impeccable/ ├── dist/ # Generated outputs (committed for users) │ ├── cursor/ # Commands + Agent Skills │ │ └── .cursor/ diff --git a/NOTICE.md b/NOTICE.md index ddf948fa0..37948f257 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -5,7 +5,7 @@ Copyright 2025 Paul Bakaus ## Anthropic frontend-design Skill -The `frontend-design` skill in this project builds on Anthropic's original frontend-design skill. +The `impeccable` skill in this project builds on Anthropic's original frontend-design skill. **Original work:** https://github.com/anthropics/skills/tree/main/skills/frontend-design **Original license:** Apache License 2.0 diff --git a/README.md b/README.md index 3dad5368c..d5c1b70f6 100644 --- a/README.md +++ b/README.md @@ -11,31 +11,31 @@ Anthropic created [frontend-design](https://github.com/anthropics/skills/tree/ma Every LLM learned from the same generic templates. Without guidance, you get the same predictable mistakes: Inter font, purple gradients, cards nested in cards, gray text on colored backgrounds. Impeccable fights that bias with: -- **An expanded skill** with 7 domain-specific reference files ([view source](source/skills/frontend-design/)) +- **An expanded skill** with 7 domain-specific reference files ([view source](source/skills/impeccable/)) - **20 steering commands** to audit, review, polish, distill, animate, and more - **Curated anti-patterns** that explicitly tell the AI what NOT to do ## What's Included -### The Skill: frontend-design +### The Skill: impeccable -A comprehensive design skill with 7 domain-specific references ([view skill](source/skills/frontend-design/SKILL.md)): +A comprehensive design skill with 7 domain-specific references ([view skill](source/skills/impeccable/SKILL.md)): | Reference | Covers | |-----------|--------| -| [typography](source/skills/frontend-design/reference/typography.md) | Type systems, font pairing, modular scales, OpenType | -| [color-and-contrast](source/skills/frontend-design/reference/color-and-contrast.md) | OKLCH, tinted neutrals, dark mode, accessibility | -| [spatial-design](source/skills/frontend-design/reference/spatial-design.md) | Spacing systems, grids, visual hierarchy | -| [motion-design](source/skills/frontend-design/reference/motion-design.md) | Easing curves, staggering, reduced motion | -| [interaction-design](source/skills/frontend-design/reference/interaction-design.md) | Forms, focus states, loading patterns | -| [responsive-design](source/skills/frontend-design/reference/responsive-design.md) | Mobile-first, fluid design, container queries | -| [ux-writing](source/skills/frontend-design/reference/ux-writing.md) | Button labels, error messages, empty states | +| [typography](source/skills/impeccable/reference/typography.md) | Type systems, font pairing, modular scales, OpenType | +| [color-and-contrast](source/skills/impeccable/reference/color-and-contrast.md) | OKLCH, tinted neutrals, dark mode, accessibility | +| [spatial-design](source/skills/impeccable/reference/spatial-design.md) | Spacing systems, grids, visual hierarchy | +| [motion-design](source/skills/impeccable/reference/motion-design.md) | Easing curves, staggering, reduced motion | +| [interaction-design](source/skills/impeccable/reference/interaction-design.md) | Forms, focus states, loading patterns | +| [responsive-design](source/skills/impeccable/reference/responsive-design.md) | Mobile-first, fluid design, container queries | +| [ux-writing](source/skills/impeccable/reference/ux-writing.md) | Button labels, error messages, empty states | ### 20 Commands | Command | What it does | |---------|--------------| -| `/teach-impeccable` | One-time setup: gather design context, save to config | +| `/impeccable teach` | One-time setup: gather design context, save to config | | `/audit` | Run technical quality checks (a11y, performance, responsive) | | `/critique` | UX design review: hierarchy, clarity, emotional resonance | | `/normalize` | Align with design system standards | @@ -202,10 +202,10 @@ Most commands accept an optional argument to focus on a specific area: Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness: ```bash -bun bin/impeccable.mjs detect src/ # scan a directory -bun bin/impeccable.mjs detect index.html # scan an HTML file -bun bin/impeccable.mjs detect https://example.com # scan a URL (Puppeteer) -bun bin/impeccable.mjs detect --fast --json . # regex-only, JSON output +bun bin/impeccable detect src/ # scan a directory +bun bin/impeccable detect index.html # scan an HTML file +bun bin/impeccable detect https://example.com # scan a URL (Puppeteer) +bun bin/impeccable detect --fast --json . # regex-only, JSON output ``` The detector catches 25 issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more). @@ -230,7 +230,7 @@ See [DEVELOP.md](DEVELOP.md) for contributor guidelines and build instructions. Apache 2.0. See [LICENSE](LICENSE). -The frontend-design skill builds on [Anthropic's original](https://github.com/anthropics/skills/tree/main/skills/frontend-design). See [NOTICE.md](NOTICE.md) for attribution. +The impeccable skill builds on [Anthropic's original frontend-design skill](https://github.com/anthropics/skills/tree/main/skills/frontend-design). See [NOTICE.md](NOTICE.md) for attribution. --- diff --git a/bin/commands/skills.mjs b/bin/commands/skills.mjs index 3c5262e93..5fd000f5e 100644 --- a/bin/commands/skills.mjs +++ b/bin/commands/skills.mjs @@ -66,8 +66,11 @@ function isAlreadyInstalled(root) { if (!existsSync(skillsDir)) continue; try { const entries = readdirSync(skillsDir); - // Look for teach-impeccable (or any prefixed variant like i-teach-impeccable) - if (entries.some(e => e === 'teach-impeccable' || e.endsWith('-teach-impeccable'))) { + // Look for 'impeccable' skill (or prefixed variant, or legacy 'teach-impeccable') + if (entries.some(e => + e === 'impeccable' || e.endsWith('-impeccable') || + e === 'teach-impeccable' || e.endsWith('-teach-impeccable') + )) { return d; } } catch {} @@ -217,15 +220,18 @@ async function install(flags) { } } - console.log(`\nDone! Run /${prefix}teach-impeccable in your AI harness to set up design context.\n`); + console.log(`\nDone! Run /${prefix}impeccable teach in your AI harness to set up design context.\n`); } -/** Detect prefix by looking for *-teach-impeccable (returns '' if unprefixed) */ +/** Detect prefix by looking for the 'impeccable' skill (or legacy 'teach-impeccable') */ function detectPrefix(root) { for (const d of PROVIDER_DIRS) { const skillsDir = join(root, d, 'skills'); if (!existsSync(skillsDir)) continue; for (const name of readdirSync(skillsDir)) { + if (name === 'impeccable') return ''; + if (name.endsWith('-impeccable') && name !== 'teach-impeccable') return name.slice(0, -'impeccable'.length); + // Legacy fallback if (name === 'teach-impeccable') return ''; if (name.endsWith('-teach-impeccable')) return name.slice(0, -'teach-impeccable'.length); } diff --git a/public/cheatsheet.html b/public/cheatsheet.html index e261b0b84..931d1eca4 100644 --- a/public/cheatsheet.html +++ b/public/cheatsheet.html @@ -194,7 +194,7 @@ const categoryOrder = ['diagnostic', 'quality', 'intensity', 'adaptation', 'enhancement', 'system']; const commandCategories = { - 'teach-impeccable': 'system', + 'impeccable': 'system', 'audit': 'diagnostic', 'critique': 'diagnostic', 'normalize': 'quality', @@ -217,7 +217,7 @@ }; const commandRelationships = { - 'teach-impeccable': { flow: 'One-time project context gathering' }, + 'impeccable': { flow: 'One-time project context gathering' }, 'audit': { leadsTo: ['normalize', 'harden', 'optimize', 'adapt', 'clarify'], flow: 'Technical quality audit' }, 'critique': { leadsTo: ['polish', 'distill', 'bolder', 'quieter', 'typeset', 'arrange'], flow: 'UX and design review' }, 'normalize': { combinesWith: ['clarify', 'adapt'], flow: 'Align with design system' }, diff --git a/public/index.html b/public/index.html index c5c03f391..8cd300a03 100644 --- a/public/index.html +++ b/public/index.html @@ -12,7 +12,7 @@ - Impeccable: The missing upgrade to Anthropic's frontend-design skill + Impeccable: The missing upgrade to Anthropic's impeccable skill @@ -74,7 +74,7 @@
What's included
- Enhanced frontend-design skill + anti-patterns + Enhanced impeccable skill + anti-patterns · 20 design skills: /polish, /audit, /typeset, /overdrive...
@@ -470,7 +470,7 @@
  • Claude Code plugin: Open /plugin, go to the Discover tab, and update from there
  • Manual ZIP: Download the latest ZIP from above and extract to your project root, overwriting existing files
    • -

    Your .impeccable.md design context file (created by /teach-impeccable) is never overwritten — your project context is preserved across updates.

    +

    Your .impeccable.md design context file (created by /impeccable teach) is never overwritten — your project context is preserved across updates.

    @@ -478,7 +478,7 @@ Commands or skills aren't appearing. What do I do?

    For commands: Type / in your AI harness and look for commands like /audit, /polish, etc. If they don't appear, double-check the files are in the correct location.

    -

    For skills: Skills are applied automatically when relevant. To verify, explicitly mention "use the frontend-design skill" in your prompt—this forces the AI to acknowledge and apply it.

    +

    For skills: Skills are applied automatically when relevant. To verify, explicitly mention "use the impeccable skill" in your prompt—this forces the AI to acknowledge and apply it.

    Tool-specific setup:

    • Cursor: Requires Nightly channel + Agent Skills enabled in Settings → Rules
      • diff --git a/public/js/components/art-gallery.js b/public/js/components/art-gallery.js index 785250c1e..509742509 100644 --- a/public/js/components/art-gallery.js +++ b/public/js/components/art-gallery.js @@ -10,8 +10,8 @@ export function renderGallery(skills) { const container = document.querySelector(".skills-gallery"); if (!container) return; - // Filter skills (hide frontend-design as per original) - const filteredSkills = skills.filter((s) => s.id !== "frontend-design"); + // Filter skills (hide impeccable as per original) + const filteredSkills = skills.filter((s) => s.id !== "impeccable"); container.innerHTML = `
      diff --git a/public/js/components/framework-viz.js b/public/js/components/framework-viz.js index 81f95302e..871c3b3f5 100644 --- a/public/js/components/framework-viz.js +++ b/public/js/components/framework-viz.js @@ -25,7 +25,7 @@ const categoryLabels = { }; const commandSymbols = { - 'teach-impeccable': 'Ti', + 'impeccable': 'Im', audit: 'Au', critique: 'Cr', normalize: 'No', @@ -48,7 +48,7 @@ const commandSymbols = { }; const commandNumbers = { - 'teach-impeccable': 0, + 'impeccable': 0, audit: 1, critique: 2, normalize: 3, polish: 4, optimize: 5, harden: 6, clarify: 7, distill: 8, adapt: 9, extract: 10, animate: 11, colorize: 12, delight: 13, bolder: 14, quieter: 15, diff --git a/public/js/data.js b/public/js/data.js index 60e13859a..8309abe5b 100644 --- a/public/js/data.js +++ b/public/js/data.js @@ -5,7 +5,7 @@ // Items that are fully complete and ready for public use // All others will show "Coming Soon" export const readySkills = [ - 'frontend-design' // Consolidated skill with all design domains + 'impeccable' // Consolidated skill with all design domains ]; export const readyCommands = [ @@ -17,9 +17,9 @@ export const betaCommands = [ 'overdrive' ]; -// Consolidated frontend-design skill with reference domains +// Consolidated impeccable skill with reference domains export const skillFocusAreas = { - 'frontend-design': [ + 'impeccable': [ { area: 'Typography', detail: 'Scale, rhythm, hierarchy, expression' }, { area: 'Color & Contrast', detail: 'Accessibility, systems, theming' }, { area: 'Spatial Design', detail: 'Layout, spacing, composition' }, @@ -30,7 +30,7 @@ export const skillFocusAreas = { ] }; -// Reference domains within the frontend-design skill +// Reference domains within the impeccable skill export const skillReferenceDomains = [ 'typography', 'color-and-contrast', @@ -42,7 +42,7 @@ export const skillReferenceDomains = [ ]; export const commandProcessSteps = { - 'teach-impeccable': ['Gather', 'Clarify', 'Document', 'Save'], + 'impeccable': ['Gather', 'Clarify', 'Document', 'Save'], 'audit': ['Scan', 'Document', 'Prioritize', 'Recommend'], 'critique': ['Evaluate', 'Critique', 'Prioritize', 'Suggest'], 'normalize': ['Analyze', 'Identify', 'Align', 'Verify'], @@ -65,7 +65,7 @@ export const commandProcessSteps = { }; export const commandCategories = { - 'teach-impeccable': 'system', + 'impeccable': 'system', 'audit': 'diagnostic', 'critique': 'diagnostic', 'normalize': 'quality', @@ -87,17 +87,17 @@ export const commandCategories = { 'overdrive': 'enhancement' }; -// Skill relationships - now consolidated into frontend-design skill -// The frontend-design skill contains all domains as reference files +// Skill relationships - now consolidated into impeccable skill +// The impeccable skill contains all domains as reference files export const skillRelationships = { - 'frontend-design': { + 'impeccable': { description: 'Comprehensive design intelligence with progressive reference loading', referenceDomains: ['typography', 'color-and-contrast', 'spatial-design', 'responsive-design', 'interaction-design', 'motion-design', 'ux-writing'] } }; export const commandRelationships = { - 'teach-impeccable': { flow: 'Setup: One-time project context gathering' }, + 'impeccable': { flow: 'Setup: One-time project context gathering' }, 'audit': { leadsTo: ['normalize', 'harden', 'optimize', 'adapt', 'clarify'], flow: 'Diagnostic: Technical quality audit' }, 'critique': { leadsTo: ['polish', 'distill', 'bolder', 'quieter', 'typeset', 'arrange'], flow: 'Diagnostic: UX and design review' }, 'normalize': { combinesWith: ['clarify', 'adapt'], flow: 'Quality: Align with design system' }, diff --git a/public/js/demo-renderer.js b/public/js/demo-renderer.js index 7304e049e..d435e5d63 100644 --- a/public/js/demo-renderer.js +++ b/public/js/demo-renderer.js @@ -25,8 +25,8 @@ export function renderCommandDemo(commandId) { const demo = getCommandDemo(commandId); if (!demo) { - // teach-impeccable is a setup command, not a visual transform — show usage guide instead - if (commandId === 'teach-impeccable') { + // impeccable is a setup command, not a visual transform — show usage guide instead + if (commandId === 'impeccable') { return `
      diff --git a/scripts/lib/utils.js b/scripts/lib/utils.js index 511c6e254..84d8dd16a 100644 --- a/scripts/lib/utils.js +++ b/scripts/lib/utils.js @@ -219,7 +219,7 @@ export function writeFile(filePath, content) { * Returns { patterns: [...], antipatterns: [...] } */ export function readPatterns(rootDir) { - const skillPath = path.join(rootDir, 'source/skills/frontend-design/SKILL.md'); + const skillPath = path.join(rootDir, 'source/skills/impeccable/SKILL.md'); if (!fs.existsSync(skillPath)) { return { patterns: [], antipatterns: [] }; @@ -387,7 +387,11 @@ function escapeRegex(str) { return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); } -const EXCLUDED_FROM_SUGGESTIONS = new Set(['teach-impeccable', 'i-teach-impeccable']); +const EXCLUDED_FROM_SUGGESTIONS = new Set([ + 'impeccable', 'i-impeccable', // foundational skill, not a steering command + 'teach-impeccable', 'i-teach-impeccable', // deprecated shim + 'frontend-design', 'i-frontend-design', // deprecated shim +]); export function replacePlaceholders(content, provider, commandNames = [], allSkillNames = []) { const placeholders = PROVIDER_PLACEHOLDERS[provider] || PROVIDER_PLACEHOLDERS['cursor']; diff --git a/skills-lock.json b/skills-lock.json new file mode 100644 index 000000000..9eef3ff1e --- /dev/null +++ b/skills-lock.json @@ -0,0 +1,110 @@ +{ + "version": 1, + "skills": { + "adapt": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "fb7cca7602be381b7b486e731fdcd480335cbb9b925e1911276f5bb9352c6b2f" + }, + "animate": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "b00cb71343fa7e987489ad330e3dd3e504ff893b9ddd2b30cacea93691b78e46" + }, + "arrange": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "698fb952e9ef0d2551a5c3421ef61e084934420e0d8371a02efb4f76f21049e8" + }, + "audit": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "eb9109e542194f8711cffce23095ef5da2deb4ed0b23f59c07e912e3931f1e17" + }, + "bolder": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "4b03286f1dc45da3e1a76a71c0c62729b4887c814dff3084345889cb4780a3a2" + }, + "clarify": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "1138379fb9f10b911094fb57b5607de8efbd77d2467fba4981ccc1c155457c6f" + }, + "colorize": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "6e292a0ba428d339615e025cab1f2692b2e6267ba247574a00545b1dac1acc5a" + }, + "critique": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "59d3facaee0d7c969f23e938c35239183d3fdd9befff526908585e55afa3a9dd" + }, + "delight": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "80127e9c695f768f5df70b9f62ad51cdfb3b4892791c4d901214b08f3be8d37e" + }, + "distill": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "ce6fbd844488a326208c1302c73b2865fa4fb20e447b6a06c038315444d6e0c5" + }, + "extract": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "1bbe30b5be73a86971f6bccb37daae84aaafceaa6d23429d6a3a0442378ac4ec" + }, + "frontend-design": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "9ebe6c652743fcde8d2ae773f34b6f548dcc8b2e75a3a30936adcd8b95dd2d16" + }, + "harden": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "f8ce420b3c78b90707704122264da76514c793ac0e12fb9540ace68d257c231c" + }, + "normalize": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "281b7f9e590e252a6aec3f5f83c5ca548c91e8bccb3fd6eee4cc7d5be0becb4d" + }, + "onboard": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "1cbedf70f906150b1b8bb70b61393eaf67e2e1311e1b5e43bde3e47411bcaa2b" + }, + "optimize": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "f7adc2a2e540a590978b567d82985062bfada83385f5ad5d50b13a127cdc96d6" + }, + "overdrive": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "3b940d458ef13afcb93ccb51ff430510aca4a9733d68fbdc335927a2636a091d" + }, + "polish": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "33a8b5195481719e954b71762de56faaabc68c479602673894e0d0e47336756b" + }, + "quieter": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "6066e73875e4770e624641355cc04662ce75d2b1d1a3673e24dcbd0ec8936297" + }, + "teach-impeccable": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "b3b5541bb9b0a260af793c7d79c2db4a436c2cd9384be34a4024c7f28af72e62" + }, + "typeset": { + "source": "pbakaus/impeccable", + "sourceType": "github", + "computedHash": "0259de15644a89550cfd6a936a8e1866dcb35d20ccc96197614459233a9bcdb3" + } + } +} diff --git a/source/skills/adapt/SKILL.md b/source/skills/adapt/SKILL.md index 81acedb7a..1f1a0d1a9 100644 --- a/source/skills/adapt/SKILL.md +++ b/source/skills/adapt/SKILL.md @@ -9,7 +9,7 @@ Adapt existing designs to work effectively across different contexts - different ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: target platforms/devices and usage contexts. --- diff --git a/source/skills/animate/SKILL.md b/source/skills/animate/SKILL.md index c9cb8482a..c5be7d04a 100644 --- a/source/skills/animate/SKILL.md +++ b/source/skills/animate/SKILL.md @@ -9,7 +9,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: performance constraints. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: performance constraints. --- diff --git a/source/skills/arrange/SKILL.md b/source/skills/arrange/SKILL.md index aa5c5c5eb..c01807946 100644 --- a/source/skills/arrange/SKILL.md +++ b/source/skills/arrange/SKILL.md @@ -9,7 +9,7 @@ Assess and improve layout and spacing that feels monotonous, crowded, or structu ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak about the current spatial design: ## Plan Layout Improvements -Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. +Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries. Create a systematic plan: diff --git a/source/skills/audit/SKILL.md b/source/skills/audit/SKILL.md index 2cbf118ff..bb9121888 100644 --- a/source/skills/audit/SKILL.md +++ b/source/skills/audit/SKILL.md @@ -7,7 +7,7 @@ user-invocable: true ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. --- @@ -65,7 +65,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the ### 5. Anti-Patterns (CRITICAL) -Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +Check against ALL the **DON'T** guidelines in the impeccable skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) diff --git a/source/skills/bolder/SKILL.md b/source/skills/bolder/SKILL.md index ba4311e61..07b1cfc99 100644 --- a/source/skills/bolder/SKILL.md +++ b/source/skills/bolder/SKILL.md @@ -9,7 +9,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. --- @@ -35,7 +35,7 @@ If any of these are unclear from the codebase, {{ask_instruction}} **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the impeccable skill before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -53,7 +53,7 @@ Create a strategy to increase impact while maintaining coherence: Systematically increase impact across these dimensions: ### Typography Amplification -- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) diff --git a/source/skills/clarify/SKILL.md b/source/skills/clarify/SKILL.md index a54940914..514a6a143 100644 --- a/source/skills/clarify/SKILL.md +++ b/source/skills/clarify/SKILL.md @@ -9,7 +9,7 @@ Identify and improve unclear, confusing, or poorly written interface text to mak ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: audience technical level and users' mental state in context. --- diff --git a/source/skills/colorize/SKILL.md b/source/skills/colorize/SKILL.md index 07e2fcf22..067713958 100644 --- a/source/skills/colorize/SKILL.md +++ b/source/skills/colorize/SKILL.md @@ -9,7 +9,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: existing brand colors. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: existing brand colors. --- diff --git a/source/skills/critique/SKILL.md b/source/skills/critique/SKILL.md index 84fc54795..c694d489a 100644 --- a/source/skills/critique/SKILL.md +++ b/source/skills/critique/SKILL.md @@ -14,7 +14,7 @@ allowed-tools: ### Step 1: Preparation -Invoke {{command_prefix}}frontend-design -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Invoke {{command_prefix}}impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments @@ -32,7 +32,7 @@ document.title = '[LLM] ' + document.title; ``` Think like a design director. Evaluate: -**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? +**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). @@ -150,7 +150,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `{{config_file}}` contains a `## Design Context` section from `teach-impeccable`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `{{config_file}}` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: diff --git a/source/skills/critique/reference/personas.md b/source/skills/critique/reference/personas.md index 0163c265d..250aa2afe 100644 --- a/source/skills/critique/reference/personas.md +++ b/source/skills/critique/reference/personas.md @@ -159,7 +159,7 @@ Choose personas based on the interface type: ## Project-Specific Personas -If `{{config_file}}` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: +If `{{config_file}}` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information: 1. Read the target audience description 2. Identify the primary user archetype not covered by the 5 predefined personas diff --git a/source/skills/delight/SKILL.md b/source/skills/delight/SKILL.md index 02f268f22..fd74d41eb 100644 --- a/source/skills/delight/SKILL.md +++ b/source/skills/delight/SKILL.md @@ -9,7 +9,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/source/skills/distill/SKILL.md b/source/skills/distill/SKILL.md index df124b2fe..eee17b88c 100644 --- a/source/skills/distill/SKILL.md +++ b/source/skills/distill/SKILL.md @@ -9,7 +9,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. --- diff --git a/source/skills/frontend-design/SKILL.md b/source/skills/frontend-design/SKILL.md index 57c87ce6d..642a7e466 100644 --- a/source/skills/frontend-design/SKILL.md +++ b/source/skills/frontend-design/SKILL.md @@ -1,147 +1,12 @@ --- name: frontend-design -description: "Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context." -license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +description: "DEPRECATED: This skill has been renamed to 'impeccable'. Run /impeccable instead." --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill has been renamed to **impeccable**. All design functionality now lives in the `{{command_prefix}}impeccable` skill. -## Context Gathering Protocol +Check if the impeccable skill is available: +- If `{{command_prefix}}impeccable` exists, use it directly. You can safely inform the user that the `frontend-design` folder is a deprecated leftover and can be deleted. +- If `{{command_prefix}}impeccable` does NOT exist, tell the user to update their skills by running `npx impeccable skills update` in their terminal. -Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. - -**Required context** — every design skill needs at minimum: -- **Target audience**: Who uses this product and in what context? -- **Use cases**: What jobs are they trying to get done? -- **Brand personality/tone**: How should the interface feel? - -Individual skills may require additional context — check the skill's preparation section for specifics. - -**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. - -**Gathering order:** -1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. -2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. -3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run {{command_prefix}}teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. - ---- - -## Design Direction - -Commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. - -Then implement working code that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -### Typography -→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* - -Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. - -**DO**: Use a modular type scale with fluid sizing (clamp) -**DO**: Vary font weights and sizes to create clear visual hierarchy -**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults -**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes -**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated - -### Color & Theme -→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* - -Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - -**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes -**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion -**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead -**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature -**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds -**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful -**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions - -### Layout & Space -→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* - -Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. - -**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations -**DO**: Use fluid spacing with clamp() that breathes on larger screens -**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis -**DON'T**: Wrap everything in cards—not everything needs a container -**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy -**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly -**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent -**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed -**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous - -### Visual Details -**DO**: Use intentional, purposeful decorative elements that reinforce brand -**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully -**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional -**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful -**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output -**DON'T**: Use modals unless there's truly no better alternative—modals are lazy - -### Motion -→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* - -Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. - -**DO**: Use motion to convey state changes—entrances, exits, feedback -**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration -**DO**: For height animations, use grid-template-rows transitions instead of animating height directly -**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only -**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly - -### Interaction -→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* - -Make interactions feel fast. Use optimistic UI—update immediately, sync later. - -**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) -**DO**: Design empty states that teach the interface, not just say "nothing here" -**DO**: Make every interactive surface feel intentional and responsive -**DON'T**: Repeat the same information—redundant headers, intros that restate the heading -**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters - -### Responsive -→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* - -**DO**: Use container queries (@container) for component-level responsiveness -**DO**: Adapt the interface for different contexts—don't just shrink it -**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it - -### UX Writing -→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* - -**DO**: Make every word earn its place -**DON'T**: Repeat information users can already see - ---- - -## The AI Slop Test - -**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -A distinctive interface should make someone ask "how was this made?" not "which AI made this?" - -Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. - ---- - -## Implementation Principles - -Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. - -Remember: {{model}} is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. +Do NOT attempt any design work from this skill. Redirect to `{{command_prefix}}impeccable` instead. diff --git a/source/skills/impeccable/SKILL.md b/source/skills/impeccable/SKILL.md new file mode 100644 index 000000000..b45aa3317 --- /dev/null +++ b/source/skills/impeccable/SKILL.md @@ -0,0 +1,219 @@ +--- +name: impeccable +description: "Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup." +argument-hint: "[teach]" +user-invocable: true +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run {{command_prefix}}impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: {{model}} is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. + +--- + +## Teach Mode + +If this skill is invoked with the argument "teach" (e.g., `{{command_prefix}}impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. + +### Step 1: Explore the Codebase + +Before asking questions, thoroughly scan the project to discover what you can: + +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** + +Note what you've learned and what remains unclear. + +### Step 2: Ask UX-Focused Questions + +{{ask_instruction}} Focus only on what you couldn't infer from the codebase: + +#### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +#### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +#### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) +- Light mode, dark mode, or both? +- Any colors that must be used or avoided? + +#### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? + +Skip questions where the answer is already clear from the codebase exploration. + +### Step 3: Write Design Context + +Synthesize your findings and the user's answers into a `## Design Context` section: + +```markdown +## Design Context + +### Users +[Who they are, their context, the job to be done] + +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] + +### Aesthetic Direction +[Visual tone, references, anti-references, theme] + +### Design Principles +[3-5 principles derived from the conversation that should guide all design decisions] +``` + +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then {{ask_instruction}} whether they'd also like the Design Context appended to {{config_file}}. If yes, append or update the section there as well. + +Confirm completion and summarize the key design principles that will now guide all future work. diff --git a/source/skills/frontend-design/reference/color-and-contrast.md b/source/skills/impeccable/reference/color-and-contrast.md similarity index 100% rename from source/skills/frontend-design/reference/color-and-contrast.md rename to source/skills/impeccable/reference/color-and-contrast.md diff --git a/source/skills/frontend-design/reference/interaction-design.md b/source/skills/impeccable/reference/interaction-design.md similarity index 100% rename from source/skills/frontend-design/reference/interaction-design.md rename to source/skills/impeccable/reference/interaction-design.md diff --git a/source/skills/frontend-design/reference/motion-design.md b/source/skills/impeccable/reference/motion-design.md similarity index 100% rename from source/skills/frontend-design/reference/motion-design.md rename to source/skills/impeccable/reference/motion-design.md diff --git a/source/skills/frontend-design/reference/responsive-design.md b/source/skills/impeccable/reference/responsive-design.md similarity index 100% rename from source/skills/frontend-design/reference/responsive-design.md rename to source/skills/impeccable/reference/responsive-design.md diff --git a/source/skills/frontend-design/reference/spatial-design.md b/source/skills/impeccable/reference/spatial-design.md similarity index 100% rename from source/skills/frontend-design/reference/spatial-design.md rename to source/skills/impeccable/reference/spatial-design.md diff --git a/source/skills/frontend-design/reference/typography.md b/source/skills/impeccable/reference/typography.md similarity index 100% rename from source/skills/frontend-design/reference/typography.md rename to source/skills/impeccable/reference/typography.md diff --git a/source/skills/frontend-design/reference/ux-writing.md b/source/skills/impeccable/reference/ux-writing.md similarity index 100% rename from source/skills/frontend-design/reference/ux-writing.md rename to source/skills/impeccable/reference/ux-writing.md diff --git a/source/skills/normalize/SKILL.md b/source/skills/normalize/SKILL.md index ed07ad065..8c6d251ad 100644 --- a/source/skills/normalize/SKILL.md +++ b/source/skills/normalize/SKILL.md @@ -9,7 +9,7 @@ Analyze and redesign the feature to perfectly match our design system standards, ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. --- diff --git a/source/skills/onboard/SKILL.md b/source/skills/onboard/SKILL.md index 6217c8127..ace82c314 100644 --- a/source/skills/onboard/SKILL.md +++ b/source/skills/onboard/SKILL.md @@ -7,7 +7,7 @@ user-invocable: true ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/source/skills/overdrive/SKILL.md b/source/skills/overdrive/SKILL.md index b67bbedb8..93d44c757 100644 --- a/source/skills/overdrive/SKILL.md +++ b/source/skills/overdrive/SKILL.md @@ -16,7 +16,7 @@ Push an interface past conventional limits. This isn't just about visual effects ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate. diff --git a/source/skills/polish/SKILL.md b/source/skills/polish/SKILL.md index a7070ef71..410290493 100644 --- a/source/skills/polish/SKILL.md +++ b/source/skills/polish/SKILL.md @@ -7,7 +7,7 @@ user-invocable: true ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: quality bar (MVP vs flagship). --- diff --git a/source/skills/quieter/SKILL.md b/source/skills/quieter/SKILL.md index ccf7d6260..3985b772a 100644 --- a/source/skills/quieter/SKILL.md +++ b/source/skills/quieter/SKILL.md @@ -9,7 +9,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. --- diff --git a/source/skills/teach-impeccable/SKILL.md b/source/skills/teach-impeccable/SKILL.md index 0fc4860ad..9e39a713e 100644 --- a/source/skills/teach-impeccable/SKILL.md +++ b/source/skills/teach-impeccable/SKILL.md @@ -1,71 +1,11 @@ --- name: teach-impeccable -description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: "DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill." user-invocable: true --- -Gather design context for this project, then persist it for all future sessions. +This command has been renamed. Run `{{command_prefix}}impeccable teach` instead. -## Step 1: Explore the Codebase +Do NOT proceed with any teach flow here. Simply inform the user: -Before asking questions, thoroughly scan the project to discover what you can: - -- **README and docs**: Project purpose, target audience, any stated goals -- **Package.json / config files**: Tech stack, dependencies, existing design libraries -- **Existing components**: Current design patterns, spacing, typography in use -- **Brand assets**: Logos, favicons, color values already defined -- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales -- **Any style guides or brand documentation** - -Note what you've learned and what remains unclear. - -## Step 2: Ask UX-Focused Questions - -{{ask_instruction}} Focus only on what you couldn't infer from the codebase: - -### Users & Purpose -- Who uses this? What's their context when using it? -- What job are they trying to get done? -- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) - -### Brand & Personality -- How would you describe the brand personality in 3 words? -- Any reference sites or apps that capture the right feel? What specifically about them? -- What should this explicitly NOT look like? Any anti-references? - -### Aesthetic Preferences -- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) -- Light mode, dark mode, or both? -- Any colors that must be used or avoided? - -### Accessibility & Inclusion -- Specific accessibility requirements? (WCAG level, known user needs) -- Considerations for reduced motion, color blindness, or other accommodations? - -Skip questions where the answer is already clear from the codebase exploration. - -## Step 3: Write Design Context - -Synthesize your findings and the user's answers into a `## Design Context` section: - -```markdown -## Design Context - -### Users -[Who they are, their context, the job to be done] - -### Brand Personality -[Voice, tone, 3-word personality, emotional goals] - -### Aesthetic Direction -[Visual tone, references, anti-references, theme] - -### Design Principles -[3-5 principles derived from the conversation that should guide all design decisions] -``` - -Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. - -Then {{ask_instruction}} whether they'd also like the Design Context appended to {{config_file}}. If yes, append or update the section there as well. - -Confirm completion and summarize the key design principles that will now guide all future work. +> The `{{command_prefix}}teach-impeccable` command has been renamed to `{{command_prefix}}impeccable teach`. Please use that instead. diff --git a/source/skills/typeset/SKILL.md b/source/skills/typeset/SKILL.md index 47db02c17..c76f77406 100644 --- a/source/skills/typeset/SKILL.md +++ b/source/skills/typeset/SKILL.md @@ -9,7 +9,7 @@ Assess and improve typography that feels generic, inconsistent, or poorly struct ## MANDATORY PREPARATION -Invoke {{command_prefix}}frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. +Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. --- @@ -46,7 +46,7 @@ Analyze what's weak or generic about the current type: ## Plan Typography Improvements -Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies. +Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies. Create a systematic plan: diff --git a/tests/lib/utils.test.js b/tests/lib/utils.test.js index 898e87b28..89cebd52d 100644 --- a/tests/lib/utils.test.js +++ b/tests/lib/utils.test.js @@ -372,13 +372,13 @@ Audit the code.`; test('should read skill with reference files', () => { const skillContent = `--- -name: frontend-design -description: Frontend design skill +name: impeccable +description: Impeccable design skill --- -Frontend design instructions.`; +Impeccable design instructions.`; - const skillDir = path.join(testRootDir, 'source/skills/frontend-design'); + const skillDir = path.join(testRootDir, 'source/skills/impeccable'); ensureDir(skillDir); fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skillContent); @@ -493,7 +493,7 @@ describe('readPatterns', () => { test('should extract DO and DON\'T patterns from SKILL.md', () => { const skillContent = `--- -name: frontend-design +name: impeccable --- ### Typography @@ -508,7 +508,7 @@ name: frontend-design **DO**: Use consistent spacing scale. **DON'T**: Nest cards inside cards.`; - const skillDir = path.join(testRootDir, 'source/skills/frontend-design'); + const skillDir = path.join(testRootDir, 'source/skills/impeccable'); ensureDir(skillDir); fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skillContent); @@ -524,14 +524,14 @@ name: frontend-design test('should normalize "Color & Theme" to "Color & Contrast"', () => { const skillContent = `--- -name: frontend-design +name: impeccable --- ### Color & Theme **DO**: Use OKLCH color space. **DON'T**: Use pure black.`; - const skillDir = path.join(testRootDir, 'source/skills/frontend-design'); + const skillDir = path.join(testRootDir, 'source/skills/impeccable'); ensureDir(skillDir); fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skillContent); @@ -541,7 +541,7 @@ name: frontend-design }); test('should handle missing SKILL.md file', () => { - ensureDir(path.join(testRootDir, 'source/skills/frontend-design')); + ensureDir(path.join(testRootDir, 'source/skills/impeccable')); const { patterns, antipatterns } = readPatterns(testRootDir); @@ -551,7 +551,7 @@ name: frontend-design test('should return patterns in consistent section order', () => { const skillContent = `--- -name: frontend-design +name: impeccable --- ### Motion @@ -563,7 +563,7 @@ name: frontend-design ### Color & Contrast **DO**: Use tinted neutrals.`; - const skillDir = path.join(testRootDir, 'source/skills/frontend-design'); + const skillDir = path.join(testRootDir, 'source/skills/impeccable'); ensureDir(skillDir); fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skillContent); @@ -610,12 +610,22 @@ describe('replacePlaceholders', () => { expect(result).toBe('Commands: /audit, /polish, /optimize'); }); - test('should exclude teach-impeccable from {{available_commands}}', () => { + test('should exclude impeccable from {{available_commands}}', () => { + const result = replacePlaceholders('Commands: {{available_commands}}', 'claude-code', ['audit', 'impeccable', 'polish']); + expect(result).toBe('Commands: /audit, /polish'); + }); + + test('should exclude i-impeccable from {{available_commands}}', () => { + const result = replacePlaceholders('Commands: {{available_commands}}', 'claude-code', ['i-audit', 'i-impeccable', 'i-polish']); + expect(result).toBe('Commands: /i-audit, /i-polish'); + }); + + test('should exclude legacy teach-impeccable from {{available_commands}}', () => { const result = replacePlaceholders('Commands: {{available_commands}}', 'claude-code', ['audit', 'teach-impeccable', 'polish']); expect(result).toBe('Commands: /audit, /polish'); }); - test('should exclude i-teach-impeccable from {{available_commands}}', () => { + test('should exclude legacy i-teach-impeccable from {{available_commands}}', () => { const result = replacePlaceholders('Commands: {{available_commands}}', 'claude-code', ['i-audit', 'i-teach-impeccable', 'i-polish']); expect(result).toBe('Commands: /i-audit, /i-polish'); }); diff --git a/tests/server/download-validation.test.js b/tests/server/download-validation.test.js index c6d0b2478..4b6b75ff7 100644 --- a/tests/server/download-validation.test.js +++ b/tests/server/download-validation.test.js @@ -28,8 +28,8 @@ describe('download provider validation', () => { describe('download file paths', () => { test('maps opencode skills into the .opencode config directory', () => { - expect(getFilePath('skill', 'opencode', 'frontend-design')).toBe( - path.join(process.cwd(), 'dist', 'opencode', '.opencode', 'skills', 'frontend-design', 'SKILL.md') + expect(getFilePath('skill', 'opencode', 'impeccable')).toBe( + path.join(process.cwd(), 'dist', 'opencode', '.opencode', 'skills', 'impeccable', 'SKILL.md') ); }); @@ -40,7 +40,7 @@ describe('download file paths', () => { }); test('rejects bundle-only providers on the individual download route', async () => { - const response = await handleFileDownload('skill', 'universal', 'frontend-design'); + const response = await handleFileDownload('skill', 'universal', 'impeccable'); expect(response.status).toBe(400); }); }); diff --git a/tests/skills-cli.test.js b/tests/skills-cli.test.js index 65f425c48..dbb94fe3a 100644 --- a/tests/skills-cli.test.js +++ b/tests/skills-cli.test.js @@ -21,7 +21,7 @@ function run(args, opts = {}) { } /** Create a fake skill installation in a temp dir */ -function createFakeSkills(root, skills = ['audit', 'polish', 'teach-impeccable'], providers = ['.claude']) { +function createFakeSkills(root, skills = ['audit', 'polish', 'impeccable'], providers = ['.claude']) { for (const provider of providers) { for (const skill of skills) { const skillDir = join(root, provider, 'skills', skill); @@ -33,7 +33,7 @@ function createFakeSkills(root, skills = ['audit', 'polish', 'teach-impeccable'] '---', '', 'Run /audit first, then /polish to finish.', - 'Use the teach-impeccable skill for setup.', + 'Use the impeccable skill for setup.', ].join('\n')); } } @@ -42,7 +42,7 @@ function createFakeSkills(root, skills = ['audit', 'polish', 'teach-impeccable'] // ─── Already-installed detection ───────────────────────────────────────────── describe('skills install: already-installed detection', () => { - test('detects teach-impeccable and bails', () => { + test('detects impeccable sentinel and bails', () => { const tmp = mkdtempSync(join(tmpdir(), 'imp-test-')); execSync('git init', { cwd: tmp }); createFakeSkills(tmp); @@ -53,13 +53,13 @@ describe('skills install: already-installed detection', () => { rmSync(tmp, { recursive: true, force: true }); }, 15000); - test('detects prefixed i-teach-impeccable', () => { + test('detects prefixed i-impeccable', () => { const tmp = mkdtempSync(join(tmpdir(), 'imp-test-')); execSync('git init', { cwd: tmp }); - const skillDir = join(tmp, '.cursor', 'skills', 'i-teach-impeccable'); + const skillDir = join(tmp, '.cursor', 'skills', 'i-impeccable'); mkdirSync(skillDir, { recursive: true }); - writeFileSync(join(skillDir, 'SKILL.md'), '---\nname: i-teach-impeccable\n---\n'); + writeFileSync(join(skillDir, 'SKILL.md'), '---\nname: i-impeccable\n---\n'); const output = run('skills install -y', { cwd: tmp }); expect(output).toContain('already installed'); @@ -75,7 +75,7 @@ describe('skills install: prefix rename', () => { beforeAll(() => { tmp = mkdtempSync(join(tmpdir(), 'imp-test-pfx-')); - createFakeSkills(tmp, ['audit', 'polish', 'teach-impeccable'], ['.claude', '.cursor']); + createFakeSkills(tmp, ['audit', 'polish', 'impeccable'], ['.claude', '.cursor']); }); afterAll(() => { @@ -146,7 +146,7 @@ console.log(JSON.stringify({ count })); const skills = readdirSync(join(tmp, '.claude', 'skills')); expect(skills).toContain('i-audit'); expect(skills).toContain('i-polish'); - expect(skills).toContain('i-teach-impeccable'); + expect(skills).toContain('i-impeccable'); expect(skills).not.toContain('audit'); expect(skills).not.toContain('polish'); }, 15000); @@ -156,7 +156,7 @@ console.log(JSON.stringify({ count })); expect(content).toContain('name: i-audit'); expect(content).toContain('/i-audit'); expect(content).toContain('/i-polish'); - expect(content).toContain('the i-teach-impeccable skill'); + expect(content).toContain('the i-impeccable skill'); // Original unprefixed references should be gone expect(content).not.toMatch(/\/audit(?=[^a-zA-Z0-9_-]|$)/); }); @@ -164,7 +164,7 @@ console.log(JSON.stringify({ count })); test('also prefixed in second provider', () => { const skills = readdirSync(join(tmp, '.cursor', 'skills')); expect(skills).toContain('i-audit'); - expect(skills).toContain('i-teach-impeccable'); + expect(skills).toContain('i-impeccable'); }); }); @@ -178,7 +178,7 @@ describe('skills update: direct download fallback', () => { execSync('git init', { cwd: tmp }); // Create stale skills that the update should overwrite - for (const skill of ['audit', 'teach-impeccable']) { + for (const skill of ['audit', 'impeccable']) { const skillDir = join(tmp, '.claude', 'skills', skill); mkdirSync(skillDir, { recursive: true }); writeFileSync(join(skillDir, 'SKILL.md'), `---\nname: ${skill}\nstale: true\n---\nOld content.\n`); @@ -215,7 +215,7 @@ describe('prefix round-trip: detect, undo, re-apply', () => { beforeAll(() => { tmp = mkdtempSync(join(tmpdir(), 'imp-test-roundtrip-')); // Create prefixed skills to simulate post-install state - for (const skill of ['audit', 'polish', 'teach-impeccable']) { + for (const skill of ['audit', 'polish', 'impeccable']) { const skillDir = join(tmp, '.claude', 'skills', 'i-' + skill); mkdirSync(skillDir, { recursive: true }); writeFileSync(join(skillDir, 'SKILL.md'), [ @@ -225,7 +225,7 @@ describe('prefix round-trip: detect, undo, re-apply', () => { '---', '', 'Run /i-audit first, then /i-polish to finish.', - 'Use the i-teach-impeccable skill for setup.', + 'Use the i-impeccable skill for setup.', ].join('\n')); } }); @@ -245,8 +245,8 @@ for (const d of DIRS) { const dir = join(root, d, 'skills'); if (!existsSync(dir)) continue; for (const name of readdirSync(dir)) { - if (name === 'teach-impeccable') { console.log(''); process.exit(); } - if (name.endsWith('-teach-impeccable')) { console.log(name.slice(0, -'teach-impeccable'.length)); process.exit(); } + if (name === 'impeccable') { console.log(''); process.exit(); } + if (name.endsWith('-impeccable')) { console.log(name.slice(0, -'impeccable'.length)); process.exit(); } } } console.log(''); @@ -301,7 +301,7 @@ console.log(JSON.stringify(readdirSync(skillsDir))); const output = JSON.parse(execSync(`node ${script}`, { encoding: 'utf8' })); expect(output).toContain('audit'); expect(output).toContain('polish'); - expect(output).toContain('teach-impeccable'); + expect(output).toContain('impeccable'); expect(output).not.toContain('i-audit'); // Verify content was un-prefixed @@ -309,9 +309,9 @@ console.log(JSON.stringify(readdirSync(skillsDir))); expect(content).toContain('name: audit'); expect(content).toContain('/audit'); expect(content).toContain('/polish'); - expect(content).toContain('the teach-impeccable skill'); + expect(content).toContain('the impeccable skill'); expect(content).not.toContain('/i-audit'); - expect(content).not.toContain('i-teach-impeccable'); + expect(content).not.toContain('i-impeccable'); }); test('re-applying prefix restores original state', () => { @@ -352,14 +352,14 @@ console.log(JSON.stringify(readdirSync(skillsDir))); const output = JSON.parse(execSync(`node ${script}`, { encoding: 'utf8' })); expect(output).toContain('i-audit'); expect(output).toContain('i-polish'); - expect(output).toContain('i-teach-impeccable'); + expect(output).toContain('i-impeccable'); expect(output).not.toContain('audit'); // Verify content was re-prefixed const content = readFileSync(join(tmp, '.claude', 'skills', 'i-audit', 'SKILL.md'), 'utf8'); expect(content).toContain('name: i-audit'); expect(content).toContain('/i-polish'); - expect(content).toContain('the i-teach-impeccable skill'); + expect(content).toContain('the i-impeccable skill'); }); });