# funboy322/avoid-ai-design architecture

> Architecture diagram of the GitHub repository funboy322/avoid-ai-design, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/funboy322/avoid-ai-design
- Repository: https://github.com/funboy322/avoid-ai-design

## Overview

#### Purpose and Distribution

`avoid-ai-design` is a portable Agent Skills specification for auditing and rewriting existing frontend UI that exhibits recognizable AI-generated design patterns. It is content-driven rather than an executable application: no build, runtime service, dependencies, API keys, or deployment infrastructure are required.

Primary installation/agent entry point: `SKILL.md`. Repository overview and user-facing installation guidance: `README.md`.

#### Invocation and Operating Modes

An AI coding client that supports the agentskills.io format loads `SKILL.md` and applies it when the user asks to audit, de-slop, or redesign existing frontend code.

Two control paths are defined:
- **rewrite** (default): audit, choose and confirm a visual direction, edit target UI files, then re-audit.
- **detect**: audit and score only; do not modify files.

The skill is intended for Claude Code, Cursor, Codex CLI, GitHub Copilot, and compatible skill consumers; compatibility is based on the plain skill-file format, not a repository-specific runtime.

Paths: `SKILL.md`, `README.md`.

#### Workflow Orchestrator

`SKILL.md` defines the agent workflow and behavioral constraints: establish scope and stack, inspect source and optionally rendered output, identify design tells, select a direction, calibrate intervention depth, rewrite, and re-audit.

The workflow preserves application-level boundaries: functionality, props, state, routing, accessibility, copy meaning, and existing design-system tokens should remain intact. New dependencies must be disclosed rather than silently introduced.

Path: `SKILL.md`.

#### Audit and Severity Model

The audit stage classifies issues by category and severity:
- **P0:** visually dominant AI signals requiring priority remediation.
- **P1:** obvious generic/default component and copy choices.
- **P2:** secondary spacing and motion issues.

Findings are expected to include source location, category, severity, rationale, and confidence. Rendering/screenshot inspection is optional; visual-only conclusions are lower confidence without it. Re-audit seeks to eliminate P0 findings.

Canonical detection signals and framework-specific remediation guidance live in `references/ai-tells-catalog.md`; workflow/output expectations are in `SKILL.md`.

#### Design-Direction Decision Boundary

Before rewrite mode edits source, the agent commits to one concrete aesthetic direction described through several defining moves. This is a confirmation boundary between diagnosis and mutation, preventing unprincipled restyling.

Intervention is calibrated by artifact context: existing design-system components receive surgical changes, while standalone pages or marketing artifacts may receive a more comprehensive visual rebuild.

Direction options and commitment guidance: `references/aesthetic-directions.md`. Decision procedure: `SKILL.md`.

#### Knowledge Base and Framework Coverage

The catalog is the primary domain knowledge source. It maps typography, color, layout, component, spacing, motion, icon, copy, and imagery tells to detection criteria and fixes for both plain HTML/CSS and React/Tailwind/shadcn contexts.

This allows the skill to operate across target repositories without embedding framework code or taking dependencies.

Paths: `references/ai-tells-catalog.md`, `references/aesthetic-directions.md`.

#### Demonstration and Maintainer Assets

A concrete before/after artifact validates the intended transformation: a generic SaaS landing page and a refined version retaining product content while changing presentation. Its audit documents discovered tells, selected direction, and changes.

Paths: `examples/demo/slop.html`, `examples/demo/refined.html`, `examples/demo/AUDIT.md`.

Launch/discoverability material is separated from the skill’s runtime behavior: `docs/LAUNCH.md`, `docs/SEO.md`.

Main entry points: [`SKILL.md`](https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md) (Skill entry point), [`README.md`](https://github.com/funboy322/avoid-ai-design/blob/main/README.md) (Repository overview), [`references/ai-tells-catalog.md`](https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md) (AI tells catalog), [`examples/demo/AUDIT.md`](https://github.com/funboy322/avoid-ai-design/blob/main/examples/demo/AUDIT.md) (Demo audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_consumer["Skill Consumers"]
  node_agent_client{{"Compatible AI coding client<br/>skill consumer"}}
  node_user_request(("Audit or redesign request<br/>invocation"))
end

subgraph group_skill["Skill Specification"]
  node_skill_md["Skill entry point<br/>agent skill<br/>[SKILL.md]"]
  node_mode_router{{"Mode selection<br/>control boundary<br/>[SKILL.md]"}}
  node_audit["UI audit &amp; scoring<br/>workflow stage<br/>[SKILL.md]"]
  node_direction_gate{{"Direction confirmation<br/>mutation boundary<br/>[SKILL.md]"}}
  node_rewrite["Constrained UI rewrite<br/>workflow stage<br/>[SKILL.md]"]
  node_reaudit["Re-audit<br/>verification stage<br/>[SKILL.md]"]
end

subgraph group_knowledge["Reference Knowledge"]
  node_catalog["AI tells catalog<br/>detection knowledge"]
  node_directions["Aesthetic directions<br/>decision knowledge"]
end

subgraph group_assets["Examples &amp; Maintainer Assets"]
  node_readme["Repository overview<br/>installation guide<br/>[README.md]"]
  node_demo_before["Generic SaaS demo<br/>before artifact<br/>[slop.html]"]
  node_demo_after["Refined SaaS demo<br/>after artifact<br/>[refined.html]"]
  node_demo_audit["Demo audit<br/>transformation record<br/>[AUDIT.md]"]
  node_launch_docs["Launch &amp; SEO material<br/>maintainer docs<br/>[LAUNCH.md]"]
  node_seo_docs["SEO guidance<br/>maintainer docs<br/>[SEO.md]"]
end

node_user_request -->|"submitted to"| node_agent_client
node_agent_client -->|"loads"| node_skill_md
node_readme -->|"points users to"| node_skill_md
node_skill_md -->|"defines"| node_mode_router
node_mode_router -->|"detect and rewrite"| node_audit
node_catalog -->|"detection criteria"| node_audit
node_audit -->|"rewrite mode only"| node_direction_gate
node_directions -->|"options"| node_direction_gate
node_direction_gate -->|"confirmed direction"| node_rewrite
node_rewrite -->|"verify changes"| node_reaudit
node_catalog -->|"P0 verification"| node_reaudit
node_demo_before -->|"presentation transformed"| node_demo_after
node_demo_audit -.->|"documents findings"| node_demo_before
node_demo_audit -.->|"documents changes"| node_demo_after
node_launch_docs -.->|"supports launch"| node_readme
node_seo_docs -.->|"supports discovery"| node_readme

click node_skill_md "https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md"
click node_mode_router "https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md"
click node_audit "https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md"
click node_direction_gate "https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md"
click node_rewrite "https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md"
click node_reaudit "https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md"
click node_catalog "https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md"
click node_directions "https://github.com/funboy322/avoid-ai-design/blob/main/references/aesthetic-directions.md"
click node_readme "https://github.com/funboy322/avoid-ai-design/blob/main/README.md"
click node_demo_before "https://github.com/funboy322/avoid-ai-design/blob/main/examples/demo/slop.html"
click node_demo_after "https://github.com/funboy322/avoid-ai-design/blob/main/examples/demo/refined.html"
click node_demo_audit "https://github.com/funboy322/avoid-ai-design/blob/main/examples/demo/AUDIT.md"
click node_launch_docs "https://github.com/funboy322/avoid-ai-design/blob/main/docs/LAUNCH.md"
click node_seo_docs "https://github.com/funboy322/avoid-ai-design/blob/main/docs/SEO.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_client,node_user_request toneBlue
class node_skill_md,node_mode_router,node_audit,node_direction_gate,node_rewrite,node_reaudit toneAmber
class node_catalog,node_directions toneMint
class node_readme,node_demo_before,node_demo_after,node_demo_audit,node_launch_docs,node_seo_docs toneRose
```

## Components

### Skill Consumers

- **Compatible AI coding client**: skill consumer · Claude Code, Cursor, Codex CLI, Copilot, or another agentskills.io client.
- **Audit or redesign request**: invocation

### Skill Specification

- [Skill entry point](https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md): agent skill · Defines workflow, modes, constraints, and output expectations. · `SKILL.md`
- [Mode selection](https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md): control boundary · Routes work to default rewrite or non-mutating detect mode. · `SKILL.md`
- [UI audit & scoring](https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md): workflow stage · Finds categorized signals with severity, rationale, location, and confidence. · `SKILL.md`
- [Direction confirmation](https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md): mutation boundary · Commits to a concrete aesthetic direction before source edits. · `SKILL.md`
- [Constrained UI rewrite](https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md): workflow stage · Changes presentation while preserving application behavior and existing boundaries. · `SKILL.md`
- [Re-audit](https://github.com/funboy322/avoid-ai-design/blob/main/SKILL.md): verification stage · Verifies P0 signals are eliminated after rewrite. · `SKILL.md`

### Reference Knowledge

- [AI tells catalog](https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md): detection knowledge · Canonical signals and remediation guidance for HTML/CSS and React/Tailwind/shadcn. · `references/ai-tells-catalog.md`
- [Aesthetic directions](https://github.com/funboy322/avoid-ai-design/blob/main/references/aesthetic-directions.md): decision knowledge · Direction options and commitment guidance. · `references/aesthetic-directions.md`

### Examples & Maintainer Assets

- [Repository overview](https://github.com/funboy322/avoid-ai-design/blob/main/README.md): installation guide · User-facing installation and usage guidance. · `README.md`
- [Generic SaaS demo](https://github.com/funboy322/avoid-ai-design/blob/main/examples/demo/slop.html): before artifact · `examples/demo/slop.html`
- [Refined SaaS demo](https://github.com/funboy322/avoid-ai-design/blob/main/examples/demo/refined.html): after artifact · `examples/demo/refined.html`
- [Demo audit](https://github.com/funboy322/avoid-ai-design/blob/main/examples/demo/AUDIT.md): transformation record · Documents tells, selected direction, and presentation changes. · `examples/demo/AUDIT.md`
- [Launch & SEO material](https://github.com/funboy322/avoid-ai-design/blob/main/docs/LAUNCH.md): maintainer docs · Discoverability material outside runtime behavior. · `docs/LAUNCH.md`
- [SEO guidance](https://github.com/funboy322/avoid-ai-design/blob/main/docs/SEO.md): maintainer docs · Discoverability material outside runtime behavior. · `docs/SEO.md`

## Connections

- Audit or redesign request → Compatible AI coding client: submitted to
- Compatible AI coding client → Skill entry point: loads
- Repository overview → Skill entry point: points users to
- Skill entry point → Mode selection: defines
- Mode selection → UI audit & scoring: detect and rewrite
- AI tells catalog → UI audit & scoring: detection criteria
- UI audit & scoring → Direction confirmation: rewrite mode only
- Aesthetic directions → Direction confirmation: options
- Direction confirmation → Constrained UI rewrite: confirmed direction
- Constrained UI rewrite → Re-audit: verify changes
- AI tells catalog → Re-audit: P0 verification
- Generic SaaS demo → Refined SaaS demo: presentation transformed
- Demo audit → Generic SaaS demo: documents findings
- Demo audit → Refined SaaS demo: documents changes
- Launch & SEO material → Repository overview: supports launch
- SEO guidance → Repository overview: supports discovery