AI Web Design

AI Web Design is a vendor-neutral skill for building web interfaces that feel intentional, specific, and appropriate to their context. It helps an AI coding agent resist recognizable AI-default aesthetics without replacing them with a different house style.

The central principle is simple:

Patterns are not banned. They are banned as unthinking defaults.

A gradient, card grid, centered hero, pill, bento layout, or glass surface may be exactly right for a project. The skill asks the agent to earn those choices from the product, audience, content, and constraints instead of reaching for them automatically.

What it does

• Establishes a clear visual premise before implementation.
• Uses available references and meaningful assets without blocking when they are absent.
• Establishes page structure before detailed styling on substantial interface work.
• Makes composition, type, color, and component choices from project context.
• Preserves existing brand language and design systems when they exist.
• Treats responsive behavior, accessibility, and real product states as design work.
• Requires a visual-review pass that looks for generic AI signatures and functional defects.

It does not prescribe a framework, component library, font, color palette, or fixed style.

Repository structure

core/
  SKILL.md                    Vendor-neutral workflow and routing
  references/                Focused design guidance
  examples/                  Bad and improved reasoning patterns
.cursor/
  rules/                     Cursor project rule
  skills/                    Thin Cursor skill adapter
.claude/
  rules/                     Claude Code path-scoped rule
  skills/                    Thin Claude skill adapter
AGENTS.md                    General agent entry point
CLAUDE.md                    Claude Code project entry point

The adapters intentionally point back to core/ rather than copying its guidance. This keeps the design principles consistent across tools.

Use with Cursor

Keep this repository, or copy its .cursor/ and core/ directories into a project. Invoke the ai-web-design skill when creating or materially changing a web interface. The rule also gives Cursor a lightweight reminder on common frontend files.

Use with Claude Code

Keep this repository, or copy its .claude/, core/, and CLAUDE.md files into a project. Ask Claude to use the ai-web-design skill for interface work.

Use with another agent

Point the agent to core/SKILL.md. AGENTS.md supplies a short repository-level instruction for agents that discover it automatically.

How the guidance works

The core workflow starts by identifying the audience, primary task, tone, content hierarchy, technical constraints, and one-sentence visual premise. It then routes to focused references for composition, typography, color, components, common anti-patterns, and visual review.

The examples distinguish a pattern from the reasoning behind it. “Never use cards” is just another rigid style rule; “do not turn every content group into a floating card without a structural reason” is a reusable design principle.

Contributing

Keep the core vendor-neutral and keep adapters thin. Add guidance only when it improves design judgment across projects. Prefer diagnostic questions, tradeoffs, and counterexamples over absolute taste rules.