Clean Design is a portable Agent Skill for agents that build or audit user interfaces. It helps prevent generic AI-generated patterns through product context, honest evidence, intentional exceptions, and a concise final audit—without prescribing a visual style, framework, or creative direction.
- Context before convention: creates a proportional brief from the user’s job, available evidence, existing system, and constraints.
- Contextual anti-patterns: reviews familiar visual recipes, decorative density, generic copy, unsupported proof, system drift, motion, and incomplete states without turning any style into a blanket ban.
- Honest exception records: documents deliberate choices with their reason and evidence rather than treating them as automatic failures.
- Actionable audits: classifies findings as Blocker, Revision, Question, or Note and records the validation performed.
- Optional companions: coordinates with Hallmark or Unslop when they are available, but never requires either tool.
- Dependency-free helpers: includes a portable package check and a limited static UI-signal audit for Node.js environments.
Clean Design works with any Agent Skills-compatible assistant. Copy this repository’s SKILL.md and scripts/ directory into the skill location supported by your agent. For a Codex project, a project-local location is .agents/skills/clean-design/.
Then ask the agent to apply the skill to a UI task:
Use Clean Design to build the billing settings screen.
The agent should inspect the affected product surface, form a compact context brief, and implement the screen with evidence-based decisions. Node.js 18 or newer is optional and only needed for the deterministic helpers.
Use Clean Design during a build or as a bounded audit of an existing change:
Use Clean Design to audit the dashboard changes in src/features/analytics.
After a relevant UI change, run the included helpers when Node.js is available:
node scripts/audit-ui.mjs src/features/analytics --context app
node scripts/check-skill.mjsaudit-ui.mjs reports narrow, reviewable signals such as placeholder copy, fake links, unverified social-proof language, suppressed focus, and transition: all. It is evidence for a human or agent review—not a design-quality score or an automatic verdict.
- SKILL.md: the complete before, during, and after workflow, exception format, audit template, and optional-tool guidance.
- GitHub Repo Banner: the header generator used by this README.
- Hallmark and Unslop: optional complementary design workflows; neither is required.
The repository has no third-party dependencies. Use Node.js 18 or newer to validate the portable skill package and its static-audit fixtures:
npm run check
npm testThe test suite verifies the skill contract and the deterministic audit signals. It does not claim to establish subjective design quality.
Contributions and corrections are welcome. Create a short-lived branch from dev, use a Clean Commit message, run the documented validation commands, and open a pull request targeting dev.
Keep proposals focused on portable, context-aware guidance. Do not add a required visual style, framework dependency, or integration with Hallmark or Unslop.
Use GitHub Issues for defects, documentation gaps, and questions about applying the skill. Include the affected section or helper output when relevant, but never include credentials, private product material, or other sensitive data.
Clean Design is licensed under the MIT License.
Created by Waren Gonzaga under WG Technology Labs, with contributions from the community.