se-frontend-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# Frontend Design

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.

## Authority Hierarchy

Every rule in this 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** -- apply in greenfield work or when the user asks for design guidance

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.

## Workflow

```
Detect context -> Plan the design -> Build -> Verify visually
```

---

## Layer 0: Context Detection

Before any design work, examine the codebase for existing design signals. This determines how much of the skill's opinionated guidance applies.

### 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 (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip. If the user declines to pick, 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.

From simonwjackson/pi-software-engineering, MIT.

More from simonwjackson/pi-software-engineering