# sexy-ui

Evolutionary aesthetics design system for AI-generated interfaces. A skill + agent pair that replaces generic SaaS defaults with intentional, attractive design.

## Problem

AI-generated UI defaults to inoffensive, homogeneous layouts — the visual equivalent of beige. Rounded corners on everything, pastel gradients, Indigo-500 accents, identical card grids. It's functional but has zero personality. There's no mechanism to encode a coherent design philosophy and enforce it across the build process.

## Context

Humans are hardwired to find certain proportions, shapes, and visual qualities attractive. The same evolutionary signals that make a fountain pen, a Ferrari, or an art deco building beautiful apply to interfaces. Good design hijacks the lizard brain — it registers as *right* before conscious evaluation. This skill distills those principles into a design session that produces a concrete, signoff-ready theme, and an agent that enforces it throughout implementation.

## Goals

- A design session (`/sexy-ui`) that produces a project-specific theme with concrete aesthetic decisions.
- A rendered theme artifact: standalone HTML file + CSS file. Real components on a real page — if hover states are designed, they work. Openable in any browser, no build step.
- A designer agent that generates the theme, advises coding agents, and audits implemented UI with specific, opinionated notes.
- Principles concrete enough to produce consistent results across any framework.

## Scope

**In — Design Principles (baked into the agent):**
- Curvature bias — intentional rounding as communication. Larger elements get generous curves (inviting, premium). Sharp edges signal business, danger, action. Not "round everything."
- Golden ratio and rule of thirds — governing proportion for layout, spacing, type scale, sizing relationships. Headlines and heroes where the eye naturally focuses.
- Symmetry and controlled asymmetry — balanced but not mirrored. Intentional breaks create visual interest. Deliberate, not sloppy.
- Waist-to-hip ratio (0.7) — element proportions for cards, containers, panels. Not tall and lurpy, not short and stubby.
- Color temperature and contrast — cohesive palette within one temperature scheme. Accents through contrast, not volume. Gradients are surgical, not features.
- Negative space — 50% of the design. Space directs attention, creates hierarchy, signals quality.
- Typography — two fonts is a relationship, three is manageable, four is the hard ceiling. Typefaces carry personality.
- Motion and easing — confident, unhurried transitions. Natural deceleration. Loaders breathe, they don't twitch.
- Visual weight and hierarchy — clear pecking order the eye knows instantly. If everything's important, nothing is.
- Texture and materiality — elements have substance. Shadows imply mass. Not skeuomorphism — presence.
- Rhythm — consistent spacing intervals. Composed, not assembled.

**In — Skill (`/sexy-ui`):**
- Conversational design session that reads project context and gathers mood/direction
- Calls the designer agent to generate the theme artifact (HTML + CSS): a page with real styled components — buttons, cards, inputs, typography scale, color swatches, spacing demos, interactive states. Looks good on its own.
- Writes theme artifact to `.dev/theme/` for downstream reference
- User reviews the rendered page in-browser and signs off before the theme becomes law

**In — Agent (`designer`):**
- Three modes:
  - **Generate**: Produce the theme artifact (HTML + CSS page with styled components and interactive states)
  - **Guide**: Before UI implementation, provide aesthetic direction to coding agents based on the approved theme
  - **Review**: Audit implemented UI against the theme. Produce a report with specific, opinionated notes — not pass/fail but smell-finding. Examples: "This card has hardcoded border-radius that doesn't match the curvature scale." "This accent color is indigo-500 — pattern-matched from SaaS template #277199." "Three different font sizes used for the same heading level." "Styles applied inconsistently between these two list views." Find the smells and point them out.
- Invocable directly by the user or by the orchestrator for the same report
- Loaded by orchestrator/sprint when UI work is in scope
- Has authority over aesthetic decisions
- References the approved theme artifact as its mandate
- Purely advisory on aesthetics — never writes business logic or application code

**Out:**
- Framework-specific implementation locked to one tool (theme is vanilla HTML/CSS; projects translate to their stack)
- Component library generation
- Accessibility rules (separate concern)
- Brand identity or logo design
- Application architecture or business logic

## Constraints

- Theme artifact must be standalone HTML + CSS — no build step, no dependencies, opens in any browser.
- Theme artifact should be comprehensive but not overengineered — a page that expresses the design decisions, not a design system website.
- Agent must stay under 200 lines per toolkit convention.
- Skill must stay under 200 lines per toolkit convention.
- Theme CSS should be structured so a coding agent can extract values and translate them to any framework's styling approach.

## Assumptions

- Build skills (/sprint, implementor) will respect the designer agent's guidance when loaded.
- The rendered HTML + CSS page provides enough visual fidelity for meaningful signoff.
- An LLM can translate evolutionary aesthetic principles into concrete CSS decisions when given project context and mood.
- The designer agent's review mode can identify aesthetic violations and inconsistencies by reading markup/styles without rendering.

## Principles

- Sexy means proportioned, relaxed, effortless. Not complicated, busy, or glass-themed.
- Every design decision traces to an evolutionary visual signal — proportion, curvature, contrast, rhythm.
- The designer is an interior designer, not a decorator. It defines what the space feels like, not what color the throw pillows are.
- Thought out, consistent, and has a voice. That's the bar.

## Open Questions

- Should the theme CSS use custom properties (CSS variables) as the primary mechanism for downstream consumption?
- Does the skill need a "refresh" mode to update an existing theme when project direction shifts?
- How does the designer agent's guide mode communicate with the implementor — a design brief document, or injected context in the implementor's prompt?