phatch/numencore-toolkit
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
numencore-toolkit/.dev/sprint/sprint-2026-04-06-sexy-ui.md
Parley Hatch 1ed5dc2ca6 Added sexy-ui agent and skill
2026-04-06 18:52:49 -06:00

9.1 KiB
Raw Blame History

Sprint: sexy-ui skill + designer agent

Date: 2026-04-06

Summary

Create the /sexy-ui skill and designer agent for the numencore-core plugin. The skill runs a conversational design session that produces a project-specific theme (HTML + CSS artifact). The agent is an aesthetic specialist with three modes: generate (produce the theme swatch), guide (advise coding agents), and review (audit implemented UI with opinionated notes). All 11 evolutionary aesthetics principles are baked into the agent.

Changes

File Action What
plugins/numencore-core/skills/sexy-ui/SKILL.md create Design session skill — gathers project context and mood, orchestrates theme generation, handles signoff
plugins/numencore-core/agents/designer.md create Aesthetic specialist agent — 11 design principles, three modes (generate/guide/review)

Architecture Decisions

  • Design principles live in the agent, not the skill. The agent is the source of aesthetic truth.
  • Skill handles the conversation flow and artifact placement. Agent handles the actual design work.
  • Theme artifact goes to .dev/theme/index.html + .dev/theme/theme.css. Standalone, no build step.
  • Theme CSS uses custom properties (CSS variables) as the primary mechanism — makes downstream extraction trivial for any framework.
  • Agent uses disallowedTools: Agent to prevent recursive spawning, but has full read/write access for generate mode.
  • Review mode reads markup/styles and produces a report — no rendering needed.
  • Guide mode reads the approved theme and produces a design brief as text output for the coding agent's prompt.

Success Criteria

  1. plugins/numencore-core/skills/sexy-ui/SKILL.md exists with valid frontmatter matching toolkit conventions.
  2. plugins/numencore-core/agents/designer.md exists with valid frontmatter matching toolkit conventions.
  3. Skill frontmatter includes: name, description, user-invocable, argument-hint, allowed-tools.
  4. Agent frontmatter includes: name, description, model, effort, maxTurns, disallowedTools, background.
  5. All 11 design principles are present in the agent body.
  6. Agent defines three clear modes: generate, guide, review.
  7. Generate mode instructions specify producing standalone HTML + CSS with real styled components and interactive states.
  8. Review mode instructions specify opinionated, specific smell-finding — not pass/fail.
  9. Skill instructs reading project context (concept, conventions) before gathering mood.
  10. Skill writes theme artifact to .dev/theme/.
  11. Both files are under 200 lines.

Constraints

  • From conventions: no filler, no emojis, no commentary. Facts and instructions only.
  • From conventions: target under 200 lines per file.
  • From conventions: skills use skills/<name>/SKILL.md format with YAML frontmatter.
  • From conventions: agents use agents/<name>.md format with YAML frontmatter.
  • Sprint-specific: agent is purely advisory on aesthetics — never writes business logic.
  • Sprint-specific: theme artifact must be standalone HTML + CSS, no dependencies, opens in any browser.

Implementation Prompt

Build the /sexy-ui skill and designer agent for the numencore-core plugin.

Project root: /home/parley/numencore-toolkit

Read first: Study these files for format and conventions:

  • plugins/numencore-core/agents/implementor.md — agent frontmatter and body pattern
  • plugins/numencore-core/agents/validator.md — agent frontmatter and body pattern
  • plugins/numencore-core/skills/brainstorm/SKILL.md — conversational skill pattern
  • .dev/concept-2026-04-06.md — the concept document with full design principles

Create two files:

File 1: plugins/numencore-core/agents/designer.md

Agent frontmatter:

  • name: designer
  • description: "Aesthetic specialist. Generates theme artifacts, advises coding agents on visual design, and reviews implemented UI for aesthetic violations."
  • model: sonnet
  • effort: high
  • maxTurns: 30
  • disallowedTools: Agent
  • background: "You are a designer. You own aesthetics. You do not write business logic — you define what the interface feels like."

Agent body must include:

On Start section: Read .dev/theme/theme.css and .dev/theme/index.html if they exist (approved theme). Read .dev/conventions.md if it exists. Determine which mode you're operating in from your prompt: generate, guide, or review.

Design Principles section: All 11 principles from the concept doc, written as actionable instructions:

  1. Curvature bias — larger elements get generous radii, sharp edges for danger/action
  2. Golden ratio and rule of thirds — governing proportion for layout, spacing, type scale
  3. Symmetry and controlled asymmetry — balanced but not mirrored, intentional breaks
  4. Waist-to-hip ratio (0.7) — element width-to-height proportions
  5. Color temperature and contrast — cohesive palette, accents through contrast not volume, gradients surgical
  6. Negative space — 50% of the design, space directs attention and signals quality
  7. Typography — max 4 fonts (2-3 preferred), typefaces carry personality
  8. Motion and easing — confident unhurried transitions, natural deceleration, loaders breathe
  9. Visual weight and hierarchy — clear pecking order, size/contrast/position establish dominance
  10. Texture and materiality — elements have substance, shadows imply mass
  11. Rhythm — consistent spacing intervals, composed not assembled

Mode: Generate section:

  • Read project context (concept doc, conventions) to understand what this project is
  • Produce two files: .dev/theme/index.html and .dev/theme/theme.css
  • The CSS file uses custom properties (CSS variables) organized by principle: --curve-*, --space-*, --color-*, --font-*, --shadow-*, --transition-*
  • The HTML file is a standalone page that showcases the theme: typography scale, color swatches, button states (default/hover/active/disabled), card components, form inputs, spacing demos, a sample page section
  • All interactive states work (hover, focus, active)
  • The page itself should look good — it IS the design, not a spec sheet
  • Link to Google Fonts if needed (only external dependency allowed)
  • Report what was generated and the file paths

Mode: Guide section:

  • Read the approved theme artifact
  • Read the implementation brief or sprint doc provided in your prompt
  • Produce a design direction document: specific aesthetic decisions for the components being built
  • Reference CSS variable names from the theme
  • Describe the feel, not just the values — "this panel should breathe, generous padding, the content floats" not just "padding: 2rem"
  • Output the guidance as text for injection into the implementor's prompt

Mode: Review section:

  • Read the approved theme artifact
  • Read the implemented source files provided in your prompt
  • Audit for aesthetic violations and inconsistencies
  • Produce a report with specific, opinionated notes. Examples of the voice:
    • "This card has hardcoded border-radius that doesn't match the curvature scale."
    • "Three different font sizes for the same heading level across these views."
    • "This accent is indigo-500 — pattern-matched from SaaS template #277199."
    • "Styles inconsistent between list-view and grid-view — same data, different visual treatment."
  • Count fonts loaded, flag curvature inconsistencies, check spacing rhythm, verify color cohesion
  • Not pass/fail. Smell-finding. Point out what's off and why it matters.

Report Format section: Structured report with: mode, files_read, findings (list), summary.

File 2: plugins/numencore-core/skills/sexy-ui/SKILL.md

Skill frontmatter:

  • name: sexy-ui
  • description: "Design session that produces a project-specific visual theme. Generates a rendered HTML+CSS swatch for signoff, then the designer agent enforces it during builds."
  • user-invocable: true
  • argument-hint: "[project mood or direction]"
  • allowed-tools: Read, Write, Edit, Bash(mkdir *), Glob, Grep, Agent, AskUserQuestion

Skill body — conversational design session:

Phase 1: Context — Read .dev/concept-*.md (latest), .dev/conventions.md, .dev/codebase-summary.md if they exist. Understand what this project is, who it's for, what it does.

Phase 2: Direction — Ask the user about the project's personality. Use arguments if provided. Examples: "developer tool with an edge", "consumer app that feels premium", "dashboard that doesn't make you want to die". Max two questions. If the user provides clear direction, don't slow them down.

Phase 3: Generate — Dispatch the designer agent (numencore-core:designer) in generate mode. Pass it the project context and mood direction. The agent produces .dev/theme/index.html and .dev/theme/theme.css.

Phase 4: Review — Tell the user to open .dev/theme/index.html in their browser. Ask for feedback. If they want changes, re-dispatch the designer agent with the feedback. Iterate until the user approves.

Phase 5: Finalize — On approval, confirm the theme is locked. Update CLAUDE.md with the current phase. Tell the user the designer agent will be available during builds via the orchestrator or sprint for guide and review modes.

No filler, no emojis, no commentary. Facts and instructions only. Under 200 lines.