john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

feat: rewrite frontend-design skill with layered architecture and visual verification (#343)

Browse Source
This commit is contained in:
Trevin Chow
2026-03-22 18:55:58 -07:00
committed by GitHub
parent 341c379168
commit 423e692726
4 changed files with 634 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
docs/brainstorms/2026-03-22-frontend-design-skill-improvement.md Normal file
View File

@@ -0,0 +1,187 @@
# Frontend Design Skill Improvement
**Date:** 2026-03-22
**Status:** Design approved, pending implementation plan
**Scope:** Rewrite `frontend-design` skill + surgical addition to `ce:work-beta`
## Context
The current `frontend-design` skill (43 lines) is a brief aesthetic manifesto forked from the Anthropic official skill. It emphasizes bold design and avoiding AI slop but lacks practical structure, concrete constraints, context-specific guidance, and any verification mechanism.
Two external sources informed this redesign:
- **Anthropic's official frontend-design skill** -- nearly identical to ours, same gaps
- **OpenAI's frontend skill** (from their "Designing Delightful Frontends with GPT-5.4" article, March 2026) -- dramatically more comprehensive with composition rules, context modules, card philosophy, copy guidelines, motion specifics, and litmus checks
Additionally, the beta workflow (`ce:plan-beta` -> `deepen-plan-beta` -> `ce:work-beta`) has no mechanism to invoke the frontend-design skill. The old `deepen-plan` discovered and applied it dynamically; `deepen-plan-beta` uses deterministic agent mapping and skips skill discovery entirely. The skill is effectively orphaned in the beta workflow.
## Design Decisions
### Authority Hierarchy
Every rule in the skill is a default, not a mandate:
1. **Existing design system / codebase patterns** -- highest priority, always respected
2. **User's explicit instructions** -- override skill defaults
3. **Skill defaults** -- only fully apply in greenfield or when user asks for design guidance
This addresses a key weakness in OpenAI's approach: their rules read as absolutes ("No cards by default", "Full-bleed hero only") without escape hatches. Users who want cards in the hero shouldn't fight their own tooling.
### Layered Architecture
The skill is structured as layers:
- **Layer 0: Context Detection** -- examine codebase for existing design signals before doing anything. Short-circuits opinionated guidance when established patterns exist.
- **Layer 1: Pre-Build Planning** -- visual thesis + content plan + interaction plan (3 short statements). Adapts to greenfield vs existing codebase.
- **Layer 2: Design Guidance Core** -- always-applicable principles (typography, color, composition, motion, accessibility, imagery). All yield to existing systems.
- **Context Modules** -- agent selects one based on what's being built:
- Module A: Landing pages & marketing (greenfield)
- Module B: Apps & dashboards (greenfield)
- Module C: Components & features (default when working inside an existing app, regardless of what's being built)
### Layer 0: Detection Signals (Concrete Checklist)
The agent looks for these specific signals when classifying the codebase:
- **Design tokens / CSS variables**: `--color-*`, `--spacing-*`, `--font-*` custom properties, theme files
- **Component libraries**: shadcn/ui, Material UI, Chakra, Ant Design, Radix, or project-specific component directories
- **CSS frameworks**: `tailwind.config.*`, `styled-components` theme, Bootstrap imports, CSS modules with consistent naming
- **Typography**: Font imports in HTML/CSS, `@font-face` declarations, Google Fonts links
- **Color palette**: Defined color scales, brand color files, design token exports
- **Animation libraries**: Framer Motion, GSAP, anime.js, Motion One, Vue Transition imports
- **Spacing / layout patterns**: Consistent spacing scale usage, grid systems, layout components
**Mode classification:**
- **Existing system**: 4+ signals detected across multiple categories. Defer to it.
- **Partial system**: 1-3 signals detected. Apply skill defaults where no convention was detected; yield to detected conventions where they exist.
- **Greenfield**: No signals detected. Full skill guidance applies.
- **Ambiguous**: Signals are contradictory or unclear. Ask the user.
### Interaction Method for User Questions
When Layer 0 needs to ask the user (ambiguous detection), use the platform's blocking question tool:
- Claude Code: `AskUserQuestion`
- Codex: `request_user_input`
- Gemini CLI: `ask_user`
- Fallback: If no question tool is available, assume "partial" mode and proceed conservatively.
### Where We Improve Beyond OpenAI
1. **Accessibility as a first-class concern** -- OpenAI's skill is pure aesthetics. We include semantic HTML, contrast ratios, focus states as peers of typography and color.
2. **Existing codebase integration** -- OpenAI has one exception line buried in the rules. We make context detection the first step and add Module C specifically for "adding a feature to an existing app" -- the most common real-world case that both OpenAI and Anthropic ignore entirely.
3. **Defaults with escape hatches** -- Two-tier anti-pattern system: "default against" (overridable preferences) vs "always avoid" (genuine quality failures). OpenAI mixes these in a flat list.
4. **Framework-aware animation defaults** -- OpenAI assumes Framer Motion. We detect existing animation libraries first. When no existing library is found, the default is framework-conditional: CSS animations as the universal baseline, Framer Motion for React, Vue Transition / Motion One for Vue, Svelte transitions for Svelte.
5. **Visual self-verification** -- Neither OpenAI nor Anthropic have any verification. We add a browser-based screenshot + assessment step with a tool preference cascade:
1. Existing project browser tooling (Playwright, Puppeteer, etc.)
2. Browser MCP tools (claude-in-chrome, etc.)
3. agent-browser CLI (default when nothing else exists -- load the `agent-browser` skill for setup)
4. Mental review against litmus checks (last resort)
6. **Responsive guidance** -- kept light (trust smart models) but present, unlike OpenAI's single mention.
7. **Performance awareness** -- careful balance, noting that heavy animations and multiple font imports have costs, without being prescriptive about specific thresholds.
8. **Copy guidance without arbitrary thresholds** -- OpenAI says "if deleting 30% of the copy improves the page, keep deleting." We use: "Every sentence should earn its place. Default to less copy, not more."
### Scope Control on Verification
Visual verification is a sanity check, not a pixel-perfect review. One pass. If there's a glaring issue, fix it. If it looks solid, move on. The goal is catching "this clearly doesn't work" before the user sees it.
### ce:work-beta Integration
A small addition to Phase 2 (Execute), after the existing Figma Design Sync section:
**UI task detection heuristic:** A task is a "UI task" if any of these are true:
- The task's implementation files include view, template, component, layout, or page files
- The task creates new user-visible routes or pages
- The plan text contains explicit "UI", "frontend", "design", "layout", or "styling" language
- The task references building or modifying something the user will see in a browser
The agent uses judgment -- these are heuristics, not a rigid classifier.
**What ce:work-beta adds:**
> For UI tasks without a Figma design, load the `frontend-design` skill before implementing. Follow its detection, guidance, and verification flow.
This is intentionally minimal:
- Doesn't duplicate skill content into ce:work-beta
- Doesn't load the skill for non-UI tasks
- Doesn't load the skill when Figma designs exist (Figma sync covers that)
- Doesn't change any other phase
**Verification screenshot reuse:** The frontend-design skill's visual verification screenshot satisfies ce:work-beta Phase 4's screenshot requirement. The agent does not need to screenshot twice -- the skill's verification output is reused for the PR.
**Relationship to design-iterator agent:** The frontend-design skill's verification is a single sanity-check pass. For iterative refinement beyond that (multiple rounds of screenshot-assess-fix), see the `design-iterator` agent. The skill does not invoke design-iterator automatically.
## Files Changed
| File | Change |
|------|--------|
| `plugins/compound-engineering/skills/frontend-design/SKILL.md` | Full rewrite |
| `plugins/compound-engineering/skills/ce-work-beta/SKILL.md` | Add ~5 lines to Phase 2 |
## Skill Description (Optimized)
```yaml
name: frontend-design
description: Build web interfaces with genuine design quality, not AI slop. Use for
any frontend work: landing pages, web apps, dashboards, admin panels, components,
interactive experiences. Activates for both greenfield builds and modifications to
existing applications. Detects existing design systems and respects them. Covers
composition, typography, color, motion, and copy. Verifies results via screenshots
before declaring done.
```
## Skill Structure (frontend-design/SKILL.md)
```
Frontmatter (name, description)
Preamble (what, authority hierarchy, workflow preview)
Layer 0: Context Detection
- Detect existing design signals
- Choose mode: existing / partial / greenfield
- Ask user if ambiguous
Layer 1: Pre-Build Planning
- Visual thesis (one sentence)
- Content plan (what goes where)
- Interaction plan (2-3 motion ideas)
Layer 2: Design Guidance Core
- Typography (2 typefaces max, distinctive choices, yields to existing)
- Color & Theme (CSS variables, one accent, no purple bias, yields to existing)
- Composition (poster mindset, cardless default, whitespace before chrome)
- Motion (2-3 intentional motions, use existing library, framework-conditional defaults)
- Accessibility (semantic HTML, WCAG AA contrast, focus states)
- Imagery (real photos, stable tonal areas, image generation when available)
Context Modules (select one)
- A: Landing Pages & Marketing (greenfield -- hero rules, section sequence, copy as product language)
- B: Apps & Dashboards (greenfield -- calm surfaces, utility copy, minimal chrome)
- C: Components & Features (default in existing apps -- match existing, inherit tokens, focus on states)
Hard Rules & Anti-Patterns
- Default against (overridable): generic card grids, purple bias, overused fonts, etc.
- Always avoid (quality floor): prompt language in UI, broken contrast, missing focus states
Litmus Checks
- Context-sensitive self-review questions
Visual Verification
- Tool cascade: existing > MCP > agent-browser > mental review
- One iteration, sanity check scope
- Include screenshot in deliverable
```
## What We Keep From Current Skill
- Strong anti-AI-slop identity and messaging
- Creative energy / encouragement to be bold in greenfield work
- Tone-picking exercise (brutally minimal, maximalist chaos, retro-futuristic...)
- "Differentiation" prompt: what makes this unforgettable?
- Framework-agnostic approach (HTML/CSS/JS, React, Vue, etc.)
## Cross-Agent Compatibility
Per AGENTS.md rules:
- Describe tools by capability class with platform hints, not Claude-specific names alone
- Use platform-agnostic question patterns (name known equivalents + fallback)
- No shell recipes for routine exploration
- Reference co-located scripts with relative paths
- Skill is written once, copied as-is to other platforms

190
docs/plans/2026-03-22-001-feat-frontend-design-skill-rewrite-beta-plan.md Normal file
View File

@@ -0,0 +1,190 @@
---
title: "feat: Rewrite frontend-design skill with layered architecture and visual verification"
type: feat
status: completed
date: 2026-03-22
origin: docs/brainstorms/2026-03-22-frontend-design-skill-improvement.md
---
# feat: Rewrite frontend-design skill with layered architecture and visual verification
## Overview
Rewrite the `frontend-design` skill from a 43-line aesthetic manifesto into a structured, layered skill that detects existing design systems, provides context-specific guidance, and verifies its own output via browser screenshots. Add a surgical trigger in `ce-work-beta` to load the skill for UI tasks without Figma designs.
## Problem Frame
The current skill provides vague creative encouragement ("be bold", "choose a BOLD aesthetic direction") but lacks practical structure. It has no mechanism to detect existing design systems, no context-specific guidance (landing pages vs dashboards vs components in existing apps), no concrete constraints, no accessibility guidance, and no verification step. The beta workflow (`ce:plan-beta` -> `deepen-plan-beta` -> `ce:work-beta`) has no way to invoke it -- the skill is effectively orphaned.
Two external sources informed the redesign: Anthropic's official frontend-design skill (nearly identical to ours, same gaps) and OpenAI's comprehensive frontend skill from March 2026 (see origin: `docs/brainstorms/2026-03-22-frontend-design-skill-improvement.md`).
## Requirements Trace
- R1. Detect existing design systems before applying opinionated guidance (Layer 0)
- R2. Enforce authority hierarchy: existing design system > user instructions > skill defaults
- R3. Provide pre-build planning step (visual thesis, content plan, interaction plan)
- R4. Cover typography, color, composition, motion, accessibility, and imagery with concrete constraints
- R5. Provide context-specific modules: landing pages, apps/dashboards, components/features
- R6. Module C (components/features) is the default when working in an existing app
- R7. Two-tier anti-pattern system: overridable defaults vs quality floor
- R8. Visual self-verification via browser screenshot with tool cascade
- R9. Cross-agent compatibility (Claude Code, Codex, Gemini CLI)
- R10. ce-work-beta loads the skill for UI tasks without Figma designs
- R11. Verification screenshot reuse -- skill's screenshot satisfies ce-work-beta Phase 4's requirement
## Scope Boundaries
- The `frontend-design` skill itself handles all design guidance and verification. ce-work-beta gets only a trigger.
- ce-work (non-beta) is not modified.
- The design-iterator agent is not modified. The skill does not invoke it.
- The agent-browser skill is upstream-vendored and not modified.
- The design-iterator's `<frontend_aesthetics>` block (which duplicates current skill content) is not cleaned up in this plan -- that is a separate follow-up.
## Context & Research
### Relevant Code and Patterns
- `plugins/compound-engineering/skills/frontend-design/SKILL.md` -- target for full rewrite (43 lines currently)
- `plugins/compound-engineering/skills/ce-work-beta/SKILL.md` -- target for surgical Phase 2 addition (lines 210-219, between Figma Design Sync and Track Progress)
- `plugins/compound-engineering/skills/ce-plan-beta/SKILL.md` -- reference for cross-agent interaction patterns (Pattern A: platform's blocking question tool with named equivalents)
- `plugins/compound-engineering/skills/reproduce-bug/SKILL.md` -- reference for cross-agent patterns
- `plugins/compound-engineering/skills/agent-browser/SKILL.md` -- upstream-vendored, reference for browser automation CLI
- `plugins/compound-engineering/agents/design/design-iterator.md` -- contains `<frontend_aesthetics>` block that overlaps with current skill; new skill will supersede this when both are loaded
- `plugins/compound-engineering/AGENTS.md` -- skill compliance checklist (cross-platform interaction, tool selection, reference rules)
### Institutional Learnings
- **Cross-platform tool references** (`docs/solutions/skill-design/compound-refresh-skill-improvements.md`): Never hardcode a single tool name with an escape hatch. Use capability-first language with platform examples and plain-text fallback. Anti-pattern table directly applicable.
- **Beta skills framework** (`docs/solutions/skill-design/beta-skills-framework.md`): frontend-design is NOT a beta skill -- it is a stable skill being improved. ce-work-beta should reference it by its stable name.
- **Codex skill conversion** (`docs/solutions/codex-skill-prompt-entrypoints.md`): Skills are copied as-is to Codex. Slash references inside SKILL.md are NOT rewritten. Use semantic wording ("load the `agent-browser` skill") rather than slash syntax.
- **Context token budget** (`docs/plans/2026-02-08-refactor-reduce-plugin-context-token-usage-plan.md`): Description field's only job is discovery. The proposed 6-line description is well-sized for the budget.
- **Script-first architecture** (`docs/solutions/skill-design/script-first-skill-architecture.md`): When a skill's core value IS the model's judgment, script-first does not apply. Frontend-design is judgment-based. Detection checklist should be inline, not in reference files.
## Key Technical Decisions
- **No `disable-model-invocation`**: The skill should auto-invoke when the model detects frontend work. Current skill does not have it; the rewrite preserves this.
- **Drop `license` frontmatter field**: Only the current frontend-design skill has this field. No other skill uses it. Drop it for consistency.
- **Inline everything in SKILL.md**: No reference files or scripts directory. The skill is pure guidance (~300-400 lines of markdown). The detection checklist, context modules, anti-patterns, litmus checks, and verification cascade all live in one file.
- **Fix ce-work-beta duplicate numbering**: The current Phase 2 has two items numbered "6." (Figma Design Sync and Track Progress). Fix this while inserting the new section.
- **Framework-conditional animation defaults**: CSS animations as universal baseline. Framer Motion for React, Vue Transition / Motion One for Vue, Svelte transitions for Svelte. Only when no existing animation library is detected.
- **Semantic skill references only**: Reference agent-browser as "load the `agent-browser` skill" not `/agent-browser`. Per AGENTS.md and Codex conversion learnings.
## Open Questions
### Resolved During Planning
- **Should the skill have `disable-model-invocation: true`?** No. It should auto-invoke for frontend work. The current skill does not have it.
- **Should Module A/B ever apply in an existing app?** No. When working inside an existing app, always default to Module C regardless of what's being built. Modules A and B are for greenfield work.
- **Should the `license` field be kept?** No. It is unique to this skill and inconsistent with all other skills.
### Deferred to Implementation
- **Exact line count of the rewritten skill**: Estimated 300-400 lines. The implementer should prioritize clarity over brevity but avoid bloat.
- **Whether the design-iterator's `<frontend_aesthetics>` block needs updating**: Out of scope. The new skill supersedes it when loaded. Cleanup is a separate follow-up.
## Implementation Units
- [x] **Unit 1: Rewrite frontend-design SKILL.md**
**Goal:** Replace the 43-line aesthetic manifesto with the full layered skill covering detection, planning, guidance, context modules, anti-patterns, litmus checks, and visual verification.
**Requirements:** R1, R2, R3, R4, R5, R6, R7, R8, R9
**Dependencies:** None
**Files:**
- Modify: `plugins/compound-engineering/skills/frontend-design/SKILL.md`
**Approach:**
- Full rewrite preserving only the `name` field from current frontmatter
- Use the optimized description from the brainstorm doc (see origin: Section "Skill Description (Optimized)")
- Structure as: Frontmatter -> Preamble (authority hierarchy, workflow preview) -> Layer 0 (context detection with concrete checklist, mode classification, cross-platform question pattern) -> Layer 1 (pre-build planning) -> Layer 2 (design guidance core with subsections for typography, color, composition, motion, accessibility, imagery) -> Context Modules (A/B/C) -> Hard Rules & Anti-Patterns (two tiers) -> Litmus Checks -> Visual Verification (tool cascade with scope control)
- Carry forward from current skill: anti-AI-slop identity, creative energy for greenfield, tone-picking exercise, differentiation prompt
- Apply AGENTS.md skill compliance checklist: imperative voice, capability-first tool references with platform examples, semantic skill references, no shell recipes for exploration, cross-platform question patterns with fallback
- All rules framed as defaults that yield to existing design systems and user instructions
- Copy guidance uses "Every sentence should earn its place. Default to less copy, not more." (not arbitrary percentage thresholds)
- Animation defaults are framework-conditional: CSS baseline, then Framer Motion (React), Vue Transition/Motion One (Vue), Svelte transitions (Svelte)
- Visual verification cascade: existing project tooling -> browser MCP tools -> agent-browser CLI (load the `agent-browser` skill for setup) -> mental review as last resort
- One verification pass with scope control ("sanity check, not pixel-perfect review")
- Note relationship to design-iterator: "For iterative refinement beyond a single pass, see the `design-iterator` agent"
**Patterns to follow:**
- `plugins/compound-engineering/skills/ce-plan-beta/SKILL.md` -- cross-agent interaction pattern (Pattern A)
- `plugins/compound-engineering/skills/reproduce-bug/SKILL.md` -- cross-agent tool reference pattern
- `plugins/compound-engineering/AGENTS.md` -- skill compliance checklist
- `docs/solutions/skill-design/compound-refresh-skill-improvements.md` -- anti-pattern table for tool references
**Test scenarios:**
- Skill passes all items in the AGENTS.md skill compliance checklist
- Description field is present and follows "what + when" format
- No hardcoded Claude-specific tool names without platform equivalents
- No slash references to other skills (uses semantic wording)
- No `TodoWrite`/`TodoRead` references
- No shell commands for routine file exploration
- Cross-platform question pattern includes AskUserQuestion, request_user_input, ask_user, and a fallback
- All design rules explicitly framed as defaults (not absolutes)
- Layer 0 detection checklist is concrete (specific file patterns and config names)
- Mode classification has clear thresholds (4+ signals = existing, 1-3 = partial, 0 = greenfield)
- Visual verification section references agent-browser semantically ("load the `agent-browser` skill")
**Verification:**
- `grep -E 'description:' plugins/compound-engineering/skills/frontend-design/SKILL.md` returns the optimized description
- `grep -E '^\`(references|assets|scripts)/[^\`]+\`' plugins/compound-engineering/skills/frontend-design/SKILL.md` returns nothing (no unlinked references)
- Manual review confirms the layered structure matches the brainstorm doc's "Skill Structure" outline
- `bun run release:validate` passes
- [x] **Unit 2: Add frontend-design trigger to ce-work-beta Phase 2**
**Goal:** Insert a conditional section in ce-work-beta Phase 2 that loads the `frontend-design` skill for UI tasks without Figma designs, and fix the duplicate item numbering.
**Requirements:** R10, R11
**Dependencies:** Unit 1 (the skill must exist in its new form for the reference to be meaningful)
**Files:**
- Modify: `plugins/compound-engineering/skills/ce-work-beta/SKILL.md`
**Approach:**
- Insert new section after Figma Design Sync (line 217) and before Track Progress (line 219)
- New section titled "Frontend Design Guidance" (if applicable), following the same conditional pattern as Figma Design Sync
- Content: UI task detection heuristic (implementation files include views/templates/components/layouts/pages, creates user-visible routes, plan text contains UI/frontend/design language, or task builds something user-visible in browser) + instruction to load the `frontend-design` skill + note that the skill's verification screenshot satisfies Phase 4's screenshot requirement
- Fix duplicate "6." numbering: Figma Design Sync = 6, Frontend Design Guidance = 7, Track Progress = 8
- Keep the addition to ~10 lines including the heuristic and the verification-reuse note
- Use semantic skill reference: "load the `frontend-design` skill" (not slash syntax)
**Patterns to follow:**
- The existing Figma Design Sync section (lines 210-217) -- same conditional "(if applicable)" pattern, same level of brevity
**Test scenarios:**
- New section follows same formatting as Figma Design Sync section
- No duplicate item numbers in Phase 2
- Semantic skill reference used (no slash syntax for frontend-design)
- Verification screenshot reuse is explicit
- `bun run release:validate` passes
**Verification:**
- Phase 2 items are numbered sequentially without duplicates
- The new section references `frontend-design` skill semantically
- The verification-reuse note is present
- `bun run release:validate` passes
## System-Wide Impact
- **Interaction graph:** The frontend-design skill is auto-invocable (no `disable-model-invocation`). When loaded, it may interact with: agent-browser CLI (for verification screenshots), browser MCP tools, or existing project browser tooling. ce-work-beta Phase 2 will conditionally trigger the skill load. The design-iterator agent's `<frontend_aesthetics>` block will be superseded when both the skill and agent are active in the same context.
- **Error propagation:** If browser tooling is unavailable for verification, the skill falls back to mental review. No hard failure path.
- **State lifecycle risks:** None. This is markdown document work -- no runtime state, no data, no migrations.
- **API surface parity:** The skill description change affects how Claude discovers and triggers the skill. The new description is broader (covers existing app modifications) which may increase trigger rate.
- **Integration coverage:** The primary integration is ce-work-beta -> frontend-design skill -> agent-browser. This flow should be manually tested end-to-end with a UI task in the beta workflow.
## Risks & Dependencies
- **Trigger rate change:** The broader description may cause the skill to trigger for borderline cases (e.g., a task that touches one CSS class). Mitigated by the Layer 0 detection step which will quickly identify "existing system" mode and short-circuit most opinionated guidance.
- **Skill length:** Estimated 300-400 lines is substantial for a skill body. Mitigated by the layered architecture -- an agent in "existing system" mode can skip Layer 2's opinionated sections entirely.
- **design-iterator overlap:** The design-iterator's `<frontend_aesthetics>` block now partially duplicates the skill's Layer 2 content. Not a functional problem (the skill supersedes when loaded) but creates maintenance overhead. Flagged for follow-up cleanup.
## Sources & References
- **Origin document:** [docs/brainstorms/2026-03-22-frontend-design-skill-improvement.md](docs/brainstorms/2026-03-22-frontend-design-skill-improvement.md)
- Related code: `plugins/compound-engineering/skills/frontend-design/SKILL.md`, `plugins/compound-engineering/skills/ce-work-beta/SKILL.md`
- External inspiration: Anthropic official frontend-design skill, OpenAI "Designing Delightful Frontends with GPT-5.4" skill (March 2026)
- Institutional learnings: `docs/solutions/skill-design/compound-refresh-skill-improvements.md`, `docs/solutions/skill-design/beta-skills-framework.md`, `docs/solutions/codex-skill-prompt-entrypoints.md`

10
plugins/compound-engineering/skills/ce-work-beta/SKILL.md
View File

@@ -216,7 +216,15 @@ This command takes a work document (plan, specification, or todo file) and execu
- Fix visual differences identified - Fix visual differences identified
- Repeat until implementation matches design - Repeat until implementation matches design
6. **Track Progress** 7. **Frontend Design Guidance** (if applicable)
For UI tasks without a Figma design -- where the implementation touches view, template, component, layout, or page files, creates user-visible routes, or the plan contains explicit UI/frontend/design language:
- Load the `frontend-design` skill before implementing
- Follow its detection, guidance, and verification flow
- If the skill produced a verification screenshot, it satisfies Phase 4's screenshot requirement -- no need to capture separately. If the skill fell back to mental review (no browser access), Phase 4's screenshot capture still applies
8. **Track Progress**
- Keep the task list updated as you complete tasks - Keep the task list updated as you complete tasks
- Note any blockers or unexpected discoveries - Note any blockers or unexpected discoveries
- Create new tasks if scope expands - Create new tasks if scope expands

275
plugins/compound-engineering/skills/frontend-design/SKILL.md
View File

@@ -1,42 +1,263 @@
--- ---
name: frontend-design name: frontend-design
description: This skill should be used when creating distinctive, production-grade frontend interfaces with high design quality. It applies when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. description: Build web interfaces with genuine design quality, not AI slop. Use for
license: Complete terms in LICENSE.txt any frontend work: landing pages, web apps, dashboards, admin panels, components,
interactive experiences. Activates for both greenfield builds and modifications to
existing applications. Detects existing design systems and respects them. Covers
composition, typography, color, motion, and copy. Verifies results via screenshots
before declaring done.
--- ---
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. # Frontend Design
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints. Guide creation of distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. This skill covers the full lifecycle: detect what exists, plan the design, build with intention, and verify visually.
## Design Thinking ## Authority Hierarchy
Before coding, understand the context and commit to a BOLD aesthetic direction: Every rule in this skill is a default, not a mandate.
- **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. 1. **Existing design system / codebase patterns** -- highest priority, always respected
2. **User's explicit instructions** -- override skill defaults
3. **Skill defaults** -- apply in greenfield work or when the user asks for design guidance
Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is: When working in an existing codebase with established patterns, follow those patterns. When the user specifies a direction that contradicts a default, follow the user.
- Production-grade and functional
- Visually striking and memorable
- Cohesive with a clear aesthetic point-of-view
- Meticulously refined in every detail
## Frontend Aesthetics Guidelines ## Workflow
Focus on: ```
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font. Detect context -> Plan the design -> Build -> Verify visually
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. ```
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. ---
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 (Space Grotesk, for example) across generations. ## Layer 0: Context Detection
**IMPORTANT**: 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. Elegance comes from executing the vision well. Before any design work, examine the codebase for existing design signals. This determines how much of the skill's opinionated guidance applies.
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. ### What to Look For
- **Design tokens / CSS variables**: `--color-*`, `--spacing-*`, `--font-*` custom properties, theme files
- **Component libraries**: shadcn/ui, Material UI, Chakra, Ant Design, Radix, or project-specific component directories
- **CSS frameworks**: `tailwind.config.*`, `styled-components` theme, Bootstrap imports, CSS modules with consistent naming
- **Typography**: Font imports in HTML/CSS, `@font-face` declarations, Google Fonts links
- **Color palette**: Defined color scales, brand color files, design token exports
- **Animation libraries**: Framer Motion, GSAP, anime.js, Motion One, Vue Transition imports
- **Spacing / layout patterns**: Consistent spacing scale usage, grid systems, layout components
Use the platform's native file-search and content-search tools (e.g., Glob/Grep in Claude Code) to scan for these signals. Do not use shell commands for routine file exploration.
### Mode Classification
Based on detected signals, choose a mode:
- **Existing system** (4+ signals across multiple categories): Defer to it. The skill's aesthetic opinions (typography, color, motion) yield to the established system. Structural guidance (composition, copy, accessibility, verification) still applies.
- **Partial system** (1-3 signals): Follow what exists; apply skill defaults only for areas where no convention was detected. For example, if Tailwind is configured but no component library exists, follow the Tailwind tokens and apply skill guidance for component structure.
- **Greenfield** (no signals detected): Full skill guidance applies.
- **Ambiguous** (signals are contradictory or unclear): Ask the user before proceeding.
### Asking the User
When context is ambiguous, use the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, assume "partial" mode and proceed conservatively.
Example question: "I found [detected signals]. Should I follow your existing design patterns or create something distinctive?"
---
## Layer 1: Pre-Build Planning
Before writing code, write three short statements. These create coherence and give the user a checkpoint to redirect before code is written.
1. **Visual thesis** -- one sentence describing the mood, material, and energy
- Greenfield examples: "Clean editorial feel, lots of whitespace, serif headlines, muted earth tones" or "Dense data-forward dashboard, monospace accents, dark surface hierarchy"
- Existing codebase: Describe the *existing* aesthetic and how the new work will extend it
2. **Content plan** -- what goes on the page and in what order
- Landing page: hero, support, detail, CTA
- App: primary workspace, nav, secondary context
- Component: what states it has, what it communicates
3. **Interaction plan** -- 2-3 specific motion ideas that change the feel
- Not "add animations" but "staggered fade-in on hero load, parallax on scroll between sections, scale-up on card hover"
- In an existing codebase, describe only the interactions being added, using the existing motion library
---
## Layer 2: Design Guidance Core
These principles apply across all context types. Each yields to existing design systems and user instructions per the authority hierarchy.
### Typography
- Choose distinctive, characterful fonts. Avoid the usual suspects (Inter, Roboto, Arial, system defaults) unless the existing codebase uses them.
- Two typefaces maximum without a clear reason for more. Pair a display/headline font with a body font.
- *Yields to existing font choices when detected in Layer 0.*
### Color & Theme
- Commit to a cohesive palette using CSS variables. A dominant color with sharp accents outperforms timid, evenly-distributed palettes.
- No purple-on-white bias, no dark-mode bias. Vary between light and dark based on context.
- One accent color by default unless the product already has a multi-color system.
- *Yields to existing color tokens when detected.*
### Composition
- Start with composition, not components. Treat the first viewport as a poster, not a document.
- Use whitespace, alignment, scale, cropping, and contrast before adding chrome (borders, shadows, cards).
- Default to cardless layouts. Cards are allowed when they serve as the container for a user interaction (clickable item, draggable unit, selectable option). If removing the card styling would not hurt comprehension, it should not be a card.
- *All composition rules are defaults. The user can override them.*
### Motion
- Ship 2-3 intentional motions for visually-led work: one entrance sequence, one scroll-linked or depth effect, one hover/reveal transition.
- Use the project's existing animation library if one is present.
- When no existing library is found, use framework-conditional defaults:
- **CSS animations** as the universal baseline
- **Framer Motion** for React projects
- **Vue Transition / Motion One** for Vue projects
- **Svelte transitions** for Svelte projects
- Motion should be noticeable in a quick recording, smooth on mobile, and consistent across the page. Remove if purely ornamental.
### Accessibility
- Semantic HTML by default: `nav`, `main`, `section`, `article`, `button` -- not divs for everything.
- Color contrast meeting WCAG AA minimum.
- Focus states on all interactive elements.
- Accessibility and aesthetics are not in tension when done well.
### Imagery
- When images are needed, prefer real or realistic photography over abstract gradients or fake 3D objects.
- Choose or generate images with a stable tonal area for text overlay.
- If image generation tools are available in the environment, use them to create contextually appropriate visuals rather than placeholder stock.
---
## Context Modules
Select the module that fits what is being built. When working inside an existing application, default to Module C regardless of what the feature is.
### Module A: Landing Pages & Marketing (Greenfield)
**Default section sequence:**
1. Hero -- brand/product, promise, CTA, one dominant visual
2. Support -- one concrete feature, offer, or proof point
3. Detail -- atmosphere, workflow, product depth, or story
4. Final CTA -- convert, start, visit, or contact
**Hero rules (defaults):**
- One composition, not a dashboard. Full-bleed image or dominant visual plane.
- Brand first, headline second, body third, CTA fourth.
- Keep the text column narrow and anchored to a calm area of the image.
- No more than 6 sections total without a clear reason.
- One H1 headline. One primary CTA above the fold.
**Copy:**
- Let the headline carry the meaning. Supporting copy is usually one short sentence.
- Write in product language, not design commentary. No prompt language or AI commentary in the UI.
- Each section gets one job: explain, prove, deepen, or convert.
- Every sentence should earn its place. Default to less copy, not more.
### Module B: Apps & Dashboards (Greenfield)
**Default patterns:**
- Calm surface hierarchy, strong typography and spacing, few colors, dense but readable information, minimal chrome.
- Organize around: primary workspace, navigation, secondary context/inspector, one clear accent for action or state.
- Cards only when the card is the interaction (clickable item, draggable unit, selectable option). If a panel can become plain layout without losing meaning, remove the card treatment.
**Copy (utility, not marketing):**
- Prioritize orientation, status, and action over promise, mood, or brand voice.
- Section headings should say what the area is or what the user can do there. Good: "Plan status", "Search metrics". Bad: "Unlock Your Potential".
- If a sentence could appear in a homepage hero, rewrite it until it sounds like product UI.
- Litmus: if an operator scans only headings, labels, and numbers, can they understand the page immediately?
### Module C: Components & Features (Default in Existing Apps)
For adding to an existing application:
- Match the existing visual language. This module is about making something that belongs, not something that stands out.
- Inherit spacing scale, border radius, color tokens, and typography from surrounding code.
- Focus on interaction quality: clear states (default, hover, active, disabled, loading, error), smooth transitions between states, obvious affordances.
- One new component should not introduce a new design system. If the existing app uses 4px border radius, do not add a component with 8px.
---
## Hard Rules & Anti-Patterns
### Default Against (Overridable)
These are the skill being opinionated. The user can override any of them.
- Generic SaaS card grid as the first impression
- Purple-on-white color schemes, dark-mode bias
- Overused fonts (Inter, Roboto, Arial, Space Grotesk, system defaults) in greenfield work
- Hero sections cluttered with stats, schedules, pill clusters, logo clouds
- Sections that repeat the same mood statement in different words
- Carousel with no narrative purpose
- Multiple competing accent colors
- Decorative gradients or abstract backgrounds standing in for real visual content
- Copy that sounds like design commentary ("Experience the seamless integration")
- Split-screen heroes where text sits on the busy side of an image
### Always Avoid (Quality Floor)
These are genuine quality failures no user would want.
- Prompt language or AI commentary leaking into the UI
- Broken contrast -- text unreadable over images or backgrounds
- Interactive elements without visible focus states
- Semantic div soup when proper HTML elements exist
---
## Litmus Checks
Quick self-review before moving to visual verification. Not all checks apply in every context -- apply judgment about which are relevant.
- Is the brand or product unmistakable in the first screen?
- Is there one strong visual anchor?
- Can the page be understood by scanning headlines only?
- Does each section have one job?
- Are cards actually necessary where they are used?
- Does motion improve hierarchy or atmosphere, or is it just there?
- Would the design feel premium if all decorative shadows were removed?
- Does the copy sound like the product, not like a prompt?
- Does the new work match the existing design system? (Module C)
---
## Visual Verification
After implementing, verify visually. This is a sanity check, not a pixel-perfect review. One pass. If there is a glaring issue, fix it. If it looks solid, move on.
### Tool Preference Cascade
Use the first available option:
1. **Existing project browser tooling** -- if Playwright, Puppeteer, Cypress, or similar is already in the project's dependencies, use it. Do not introduce new dependencies just for verification.
2. **Browser MCP tools** -- if browser automation tools (e.g., claude-in-chrome) are available in the agent's environment, use them.
3. **agent-browser CLI** -- if nothing else is available, this is the default. Load the `agent-browser` skill for installation and usage instructions.
4. **Mental review** -- if no browser access is possible (headless CI, no permissions to install), apply the litmus checks as a self-review and note that visual verification was skipped.
### What to Assess
- Does the output match the visual thesis from the pre-build plan?
- Are there obvious visual problems (broken layout, unreadable text, missing images)?
- Does it look like the context module intended (landing page feels like a landing page, dashboard feels like a dashboard, component fits its surroundings)?
### Scope Control
One iteration. Take a screenshot, assess against the litmus checks, fix any glaring issues, and move on. Include the screenshot in the deliverable (PR description, conversation output, etc.).
For iterative refinement beyond a single pass (multiple rounds of screenshot-assess-fix), see the `compound-engineering:design:design-iterator` agent.
---
## Creative Energy
This skill provides structure, but the goal is distinctive work that avoids AI slop -- not formulaic output.
For greenfield work, commit to a bold aesthetic direction. Consider the tone: brutally minimal, maximalist, retro-futuristic, organic/natural, luxury/refined, playful, editorial, brutalist, art deco, soft/pastel, industrial -- or invent something that fits the context. There are endless flavors. Use these for inspiration but design one that is true to the project.
Ask: what makes this unforgettable? What is the one thing someone will remember?
Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well, not from intensity.