prodigeui

Imported from prodigeproject/prodigeui (AGENTS.md). Install upstream with npx skills add prodigeproject/prodigeui. Copyright stays with the author.

ProdigeUI — Agent Entry Point

⚠️ Read PHILOSOPHY.md first. ProdigeUI has two modes. In Creative Mode (vague brief) you ARE the designer — produce cinematic, craft-rich output using the craft/ library; it must look visibly BETTER than raw AI, never merely "safe." In Enhancement Mode (specific brief) honor the designer's intent, execute their chosen techniques at reference quality, and DO NO HARM (never break assets, slow interaction, or add jank).

⚠️ Rules prevent bad output; craft produces great output. You need BOTH. The tokens, rules, and anti-slop gate below are the floor. For any expressive build, start at craft/AGENTS.md and pick a signature — otherwise output will be competent but forgettable, which is a FAILURE for expressive work.

This document is the canonical entry point for AI agents using ProdigeUI. Read this file first. It tells you what ProdigeUI is, where things live, and how to work.

System Purpose

ProdigeUI is a portable UI/UX knowledge system that equips you (AI agent) with:

• Measurable design rules backed by theory and research (80+ books, 39 repos — 119 sources indexed in research/research-log.json)
• A three-layer token system as the single source of visual truth
• Enterprise-grade component specifications (states, accessibility, variants)
• Accessible and purposeful motion presets with reduce-motion compliance
• Professional prompt templates for 6 use-case categories
• A quality gate ensuring output is free of "AI slop"
• The Three Dials system for calibrating aesthetic direction per project

Use these artifacts as the foundation for every visual decision. Define concrete values once at a token boundary; repeated component styling must consume semantic variables rather than repeating raw literals.

Available Skills

Skills are structured capability units stored in skills/. Each has a SKILL.md with frontmatter (name, description, triggers) and step-by-step workflow instructions.

ProdigeUI — Agent Entry Point

⚠️ Read PHILOSOPHY.md first. ProdigeUI has two modes. In Creative Mode (vague brief) you ARE the designer — produce cinematic, craft-rich output using the craft/ library; it must look visibly BETTER than raw AI, never merely "safe." In Enhancement Mode (specific brief) honor the designer's intent, execute their chosen techniques at reference quality, and DO NO HARM (never break assets, slow interaction, or add jank).

⚠️ Rules prevent bad output; craft produces great output. You need BOTH. The tokens, rules, and anti-slop gate below are the floor. For any expressive build, start at craft/AGENTS.md and pick a signature — otherwise output will be competent but forgettable, which is a FAILURE for expressive work.

This document is the canonical entry point for AI agents using ProdigeUI. Read this file first. It tells you what ProdigeUI is, where things live, and how to work.

System Purpose

ProdigeUI is a Generative UI/UX Knowledge Engine that equips AI agents to synthesize world-class interfaces driven by 4 core pillars:

1. Intent & Product Read: Deeply analyzing product domain, user persona, and emotional positioning.
2. Dynamic Taste Engine: Deriving custom HSL color harmonies (themes/generative-theme-synthesis.md), font pairings, material depth, and spatial rhythms dynamically for ANY brief.
3. High-Craft Copywriting System: Writing authentic domain storytelling copy (craft/high-craft-copywriting.md) while strictly prohibiting prompt instruction leaks (e.g. (CLICK TO...)).
4. Non-Negotiable Guardrails: Enforcing WCAG AA contrast (>=4.5:1 / 7.0:1+), 0 inline HTML styles, prefers-reduced-motion, and strict container boundary containment (overflow: hidden;).

Available Skills

Skills are structured capability units stored in skills/. Each has a SKILL.md with frontmatter (name, description, triggers) and step-by-step workflow instructions.

The registry above is a subset. See skills/AGENTS.md for the full skill list (14 skills).

How to find and run a skill:

1. Match your need against the triggers above (or browse skills/AGENTS.md)
2. Open the skill folder and read SKILL.md
3. Follow the numbered steps — each references specific ProdigeUI artifacts
4. Validate output with Quality Gate before delivering

Generative Workflow (4-Pillar Pipeline)

Every UI/UX design task follows this dynamic sequence:

1. INTENT & PRODUCT READ   — Complete `craft/intent-driven-art-direction.md`: product, user, market, job, evidence, media, and constraints.
2. DYNAMIC TASTE SYNTHESIS — Derive semantic tokens, typography, spatial roles, and media treatment from that read; do not select a universal skin.
3. GENERATIVE ENGINE CRAFT — Choose layout and interaction from the information job; use canvas or JS only when it improves comprehension or feedback.
4. HIGH-CRAFT COPYWRITING — Write authentic domain storytelling copy (0 prompt leaks / hints).
5. QUALITY GATE CHECK     — Validate against WCAG AA, 0 inline styles, overflow containment, & anti-slop rules.

If an unforeseen Quality Gate failure remains, loop back to the step that produced the violation and fix it, then record why the preflight missed it so the contract can improve. For expressive output, "competent but forgettable" is a FAILURE — loop back to Craft Selection (Step 3). Only deliver once the negative gate passes AND (for expressive work) the craft-presence rubric scores >= 9/12.

See skills/prodige-ui-end-to-end/SKILL.md for the detailed version of each step.

Mandatory intent route

Before dynamic tokens, profile selection, or craft recipes, read craft/intent-driven-art-direction.md. Record the product, primary user, target market, user job, emotional shift, evidence/media strategy, and constraints. The selected route must explain information hierarchy and layout; it must never be used as a preset for color, typography, section order, or geometry. If the brief changes product or audience, re-derive those decisions.

Then read craft/model-robust-generation.md and canonical/accepted-quality.profile.json for the semantic quality floor and profile transfer rules. These documents constrain truthfulness, accessibility, and evidence quality; they do not choose a universal visual style.

Evidence-led expressive route

When the selected quality profile is expressiveStudio, read craft/evidence-led-studio-composition.md after the Design Read and before implementation. It adds a claim-to-proof decision, a truthful local-media route, non-generic work evidence, and a closing invitation without prescribing a benchmark geometry.

When the brief or reference preference calls for a quiet, iconic, editorial first viewport, also read craft/quiet-evidence-mode.md. Select quietEvidence before implementation and record its hero budget privately; it preserves visual mass and negative space while moving detailed proof into the work chapter.

When the user explicitly selects an existing expressive composition as the reference and asks for tuning without changing its first-viewport character, read craft/baseline-preserving-studio-tuning.md after the quiet-evidence guidance. Select baselinePreserving and tune the work chapter, copy, or closing in isolation; do not escalate the request into a new hero treatment.

Core Principles

1. Token-first: Repeated visual roles MUST be declared at a token-definition boundary and consumed through semantic/component variables. Concrete hex, px, or rem values are valid inside token definitions and one-off generated artwork; repeating them directly across component declarations is a failure.
2. Rule-backed: Every design decision is supported by measurable Design Rules with rationale traced to research sources.
3. Three Dials calibration: Every project sets DESIGN_VARIANCE, MOTION_INTENSITY, and VISUAL_DENSITY (0.0-1.0 each) to calibrate output appropriately for the use-case.
4. Accessible: WCAG 2.1 AA minimum — 4.5:1 contrast (normal text), 3:1 (large text), keyboard navigation, ARIA roles, focus indicators.
5. Anti-AI-slop: Use the Quality Gate (quality-gate/anti-ai-slop.checklist.md) to ensure expert-quality output. This is ProdigeUI's key differentiator — it detects and prevents generic, purposeless, inconsistent design output.
6. Traceable: Design decisions trace back to specific research sources in research/.
7. Atomic composition: Components follow atoms → molecules → organisms hierarchy.
8. Route before you invent: For functional product UI, consider an official design system per craft/design-system-routing.md before building a bespoke token layer.
9. Motion & interaction craft: For any interactive build, apply craft/patterns/motion-craft.md and craft/patterns/interaction-patterns.md.
10. Zero Inline HTML Styles: Never emit inline style="..." attributes in HTML markup. All component styles must be declared via CSS classes consuming custom properties (var(--prodigeui-*)).
11. Mandatory Reduced Motion: Every generated stylesheet must include @media (prefers-reduced-motion: reduce) to disable/simplify layout transforms and animations for sensitive users.
12. Stacking Layer Safety: Section wrappers containing pseudo-elements or absolute overlays MUST declare isolation: isolate;. Interactive CTA elements MUST explicitly own position: relative; z-index: 2;.
13. Dynamic Recipe Derivation: Do NOT copy hardcoded recipe artifacts (e.g. rotate(1deg) cards or 11:18 → 11:19 watermarks) verbatim across unrelated briefs. Layouts must be organically synthesized for the specific product domain.
14. Material Depth & Inset Lighting: Avoid flat, generic cards. Elevate surfaces with subtle top inset highlights (box-shadow: inset 0 1px 0 0 rgba(255,255,255,0.1)), backdrop blur (backdrop-filter: blur(12px) saturate(160%)), and atmospheric light sweeps.
15. Intent-fit proof: The hero must foreground the most truthful evidence for the product and user job. That may be a product state, real/generated photography, editorial work, diagram, data view, or an interactive canvas. Static imagery is valid when looking, material inspection, or trust is the job.
16. Conditional engine craft: MOTION_INTENSITY and VARIANCE calibrate ambition; they do not mandate WebGL, particles, or a JS canvas. Add an interactive engine only when it explains a mechanism, supports comparison, or provides meaningful feedback. A static page is valid when it is the clearest product-specific answer.
17. Harmonized Storytelling & Interactive Anchors: Interactive canvas anchors or live JS widgets MUST NOT displace core domain storytelling typography, editorial project titles, or contextual metadata. High-craft interfaces harmonize editorial storytelling WITH interactive technical anchors.
18. Strict Container Boundary Containment: All container surfaces with rounded borders (border-radius) that enclose media viewports, image grids, or canvas anchors MUST declare overflow: hidden; to ensure 100% pixel-perfect containment without border bleeding.

Dynamic art-direction system

• craft/intent-driven-art-direction.md — required product, audience, evidence, media, and route read
• themes/generative-theme-synthesis.md — role-based token derivation and contrast verification
• Static theme JSON files are not a visual catalog. Do not recreate them as hidden palettes or category defaults.

Motion Library

• motion/motion.tokens.json — duration and easing tokens
• motion/presets/enter-exit.json, state-transition.json, hover-focus.json, scroll-based.json
• motion/principles.md — purpose-driven motion principles

Component Library

• components/components.manifest.json — 55 components (16 atoms, 18 molecules, 21 organisms)
• components/composition-guidelines.md — atomic design composition rules

Design Rules (JSON + narrative)

• design-rules/typography.rules.json, color.rules.json, layout.rules.json, structure.rules.json
• design-rules/form.rules.json, responsive.rules.json, data-visualization.rules.json, advanced-methodology.rules.json
• design-rules/design-rules.md — full rationale with book references

Use-Case Guides (6 categories)

• use-cases/saas/guide.md
• use-cases/landing/guide.md
• use-cases/ecommerce/guide.md
• use-cases/portfolio/guide.md
• use-cases/hris/guide.md
• use-cases/agentic-app/guide.md

Quality Gate

• quality-gate/criteria.json — measurable pass/fail criteria
• quality-gate/anti-ai-slop.checklist.md — expert vs generic output indicators
• quality-gate/report.schema.json — report format

Design System Cohesion

• design-system/design-system.md — dependency graph between all 6 core artifacts
• design-system/entry-point.md — recommended reading order

Assets

• assets/assets.manifest.json — icons, fonts, illustrations with license metadata

Research

• research/research-log.json — index of all research notes
• research/synthesis.md — cross-source consolidated findings

Quick Start for Agents

1. You receive a UI brief → Start with the Intent & Art Direction Read
2. You need a specific component → Open components/components.manifest.json
3. You need color/spacing values → Synthesize semantic roles after the intent read
4. You want to check your work → Run skills/quality-check/SKILL.md
5. You need to create a brand token system → Use the dynamic synthesis contract; do not add a sector preset
6. You need to add/change tokens → Run skills/token-management/SKILL.md

Anti-AI-Slop: The Key Differentiator

The quality-gate/anti-ai-slop.checklist.md defines what separates expert UI from generic AI output:

• Spacing rhythm — consistent, intentional, not arbitrary margins
• Visual hierarchy — purposeful sizing/weight, not random
• Motion purpose — every animation has a documented reason
• Color coherence — roles and relationships, not decoration
• Typography discipline — scale adherence, limited weights, vertical rhythm
• Whitespace intent — breathing room with purpose, not filler

Run this checklist as the final gate on every output. If it fails, iterate.

Reference

• Full artifact list: manifest.json
• Installation instructions: README.md
• Skill registry (detailed): skills/AGENTS.md
• Research index: research/research-log.json
• Research synthesis: research/synthesis.md