agentic-designer

AI-native design system for coding agents.

Not a component library itself. @imehr/agentic-designer bridges three component libraries (shadcn/ui, Ant Design, Radix) with design philosophy, automated critique, and canvas sync. It installs into Claude Code, Codex, OpenCode, Gemini CLI, and GitHub Copilot, giving any coding agent the design intelligence to produce brand-aligned, accessible React applications.

Table of Contents

• Architecture
• Quick Start
• CLI Reference
• Skills
• Design Systems
• DESIGN.md Format
• Multi-Platform Install
• Project Structure
• Development
• Lineage
• License

Architecture

Three layers, each with a distinct responsibility.

Layer 1: Design Intelligence

• 31 skills covering web prototypes, dashboards, decks, mobile apps, finance, and operations
• 20 design philosophies (Pentagram information architecture, Kenya Hara minimalism, Sagmeister experimental, and 17 others)
• 5D critique engine scoring across Philosophical Coherence, Visual Hierarchy, Execution Craft, Functionality, and Innovation
• Anti-slop detector catching hardcoded colors, missing ARIA, purple gradients, and 20+ other AI-generated UI mistakes
• Junior Designer workflow forcing agents to propose before generating

Layer 2: Component Library Bridge

A token-mapping layer that translates design intent into concrete component output:

| Library | Tier | When to Use | |---------|------|-------------| | shadcn/ui | Default | Full source control, agent can read and modify freely | | Ant Design | Enterprise | Internal tools, ProComponents, advanced data tables | | Radix + Tailwind | Minimal | Maximum pixel control, custom design systems |

The bridge auto-detects which library is in use and maps tokens to the correct variable format. It is bidirectional: it also reads existing components and extracts embedded design tokens.

Layer 3: Developer Tooling

• CLI: 10 commands -- init, generate, critique, audit, extract, syncd, sync status, theme apply/create/list/export, skill list/load/info, install
• Scaffold templates: Next.js + shadcn, React + Ant Design, React + Radix + Tailwind
• Sync daemon: Bidirectional sync between code and design canvases (OpenPencil, Paper, Figma)
• Multi-platform installer: One command to install into any supported agent

+================================================================+
|                     agentic-designer                            |
|                                                                 |
|  Layer 1: Design Intelligence                                   |
|  +----------------------------------------------------------+  |
|  | DESIGN.md | 11 Design Systems | 5D Critique              |  |
|  | 31 Skills | 20 Philosophies | Anti-Slop | Craft Refs     |  |
|  +-----------------------------+----------------------------+  |
|                                |                                |
|  Layer 2: Component Library Bridge                              |
|  +----------------------------------------------------------+  |
|  | Token Mapping | Variant Translation | Style Bridges        |  |
|  | shadcn <-> antd <-> radix | Extraction Engine             |  |
|  +-----------------------------+----------------------------+  |
|                                |                                |
|  Layer 3: Developer Tooling                                     |
|  +----------------------------------------------------------+  |
|  | CLI | syncd Daemon | Agent Hooks | CI Actions              |  |
|  | Skill Loader | Audit Engine | Theme Manager                |  |
|  +-----------------------------+----------------------------+  |
|                                |                                |
+--------------------------------+--------------------------------+
                                 |
          +----------------------+----------------------+
          |                      |                      |
          v                      v                      v
    +-----------+         +-------------+        +-------------+
    | AI Agent  |-------->| Code Gen +  |------->| Component   |
    | Session   |         | CLI Commands|        | Library     |
    +-----------+         +------+------+        +------+------+
                                |                        |
                                v                        v
                         +-------------+         +--------------+
                         | Sync Daemon |<------->| Design Canvas|
                         |  (syncd)    |         | OpenPencil / |
                         +-------------+         | Paper / Figma|
                                                 +--------------+

Quick Start

npx @imehr/agentic-designer init my-app
cd my-app
npm run dev

The generated project includes:

• A DESIGN.md encoding the chosen brand's design language
• CSS variables mapped to the design token system
• Component library scaffolding (shadcn by default)
• Agent hooks for self-correction
• Pre-commit audit configuration

Specify a stack and brand:

npx @imehr/agentic-designer init my-app --stack next+tailwind+shadcn --brand linear
npx @imehr/agentic-designer init admin-panel --stack react+antd --brand stripe
npx @imehr/agentic-designer init portfolio --stack react+tailwind+radix --brand apple

CLI Reference

| Command | Description | |---------|-------------| | init | Create a new project with design system, component library, and agent configuration | | generate | Generate a component from a design intent specification | | critique | Run 5D critique framework against a component or directory | | audit | Audit files for design violations (hardcoded colors, missing ARIA, token breaks) | | extract | Reverse-engineer design tokens from an existing codebase | | syncd | Start the sync daemon for bidirectional canvas sync | | sync status | Check the current sync state | | theme apply | Apply a built-in design system as the active theme | | theme create | Create a custom theme derived from an existing design system | | theme list | List all available themes | | theme export | Export the active theme to a portable format | | skill list | List all available skills | | skill load | Load a specific skill into the current agent session | | skill info | Show detailed information about a specific skill | | install | Install into a specific agent platform |

Full command documentation: docs/cli-reference.md

Skills

31 skills, each a self-contained SKILL.md with instructions, constraints, and examples. Loaded on demand to keep agent context lean.

| Skill | Mode | Description | |-------|------|-------------| | web-prototype | prototype | Single-page web prototype -- landings, marketing, hero pages | | dashboard | prototype | Analytics or admin dashboard with data cards, charts, and navigation | | mobile-app | prototype | Mobile app screen or flow -- iOS/Android style interfaces | | saas-landing | prototype | Full SaaS landing page with hero, features, pricing, CTA, footer | | design-system | template | Complete design system reference page with token previews | | critique | prototype | Run 5D critique on a component and generate improvement suggestions | | pricing-page | prototype | Pricing tiers with comparison table, toggle, and feature matrix | | docs-page | prototype | Sidebar navigation + content area + search for documentation sites | | blog-post | prototype | Article reading view with typography-first layout and metadata | | email-marketing | template | Transactional or marketing email with inline styles and table layout | | social-carousel | prototype | Swipeable social media carousel with text overlays and branded frames | | mobile-onboarding | prototype | Step-by-step mobile onboarding with illustrations and progress indicators | | gamified-app | prototype | App with gamification elements -- points, badges, streaks, leaderboards | | magazine-poster | prototype | Editorial-style poster layout with dramatic typography and image treatment | | motion-frames | prototype | Animated frame sequences with keyframe transitions and easing | | sprite-animation | prototype | CSS/JS sprite sheet animation with frame control and looping | | wireframe-sketch | prototype | Low-fidelity wireframe layout with sketch-style rendering | | tweaks | prototype | Apply incremental design tweaks and visual refinements to existing components | | dating-web | prototype | Dating and matchmaking dashboard with match feed, KPIs, and profile cards | | digital-eguide | prototype | Two-spread digital e-guide with cover page and lesson spread | | pm-spec | template | Product specification page with sections, tables, and status indicators | | eng-runbook | template | Operational runbook with procedures, alerts, and status dashboards | | finance-report | prototype | Financial report with tables, charts, KPIs, and period comparisons | | invoice | template | Printable invoice with line items, totals, and branding | | hr-onboarding | prototype | Employee onboarding portal with tasks, documents, and progress tracking | | kanban-board | prototype | Drag-and-drop task board with columns, cards, and swim lanes | | team-okrs | prototype | OKR tracking view with objectives, key results, and progress bars | | meeting-notes | template | Structured meeting notes with action items, decisions, and attendees | | simple-deck | deck | Presentation slide deck with title, content, and section slides | | guizang-ppt | deck | Chinese-style presentation with Guizang aesthetic and vertical text support | | weekly-update | template | Weekly status update with highlights, blockers, and metrics summary |

npx @imehr/agentic-designer skill list
npx @imehr/agentic-designer skill load dashboard
npx @imehr/agentic-designer skill info dashboard

Design Systems

11 built-in design systems. Each includes a complete DESIGN.md with color, typography, spacing, radius, shadows, motion, icons, and layout tokens.

| System | Description | Preview | |--------|-------------|---------| | default | Neutral Modern -- clean, adaptable starter | #3B82F6 #18181B #FAFAF9 | | linear | Dark, fast, keyboard-first | #5E6AD2 #1a1a2e #fff | | stripe | Clean, trustworthy, professional | #635BFF #0A2540 #fff | | vercel | Minimal, fast, black and white | #000 #fff #444 | | apple | Refined, spacious, premium | #0071E3 #F5F5F7 #1D1D1F | | anthropic | Warm, academic, human | #DA7756 #FAF7F5 #1A1A1A | | supabase | Developer-docs, code-forward | #3ECF8E #171717 #fff | | figma | Creative, playful, professional | #A259FF #F24E1E #0ACF83 | | notion | Functional, content-first, minimal | #000 #fff #37352F | | tesla | Bold, premium, imagery-driven | #CC0000 #000 #fff | | cyberpunk | Neon, glitch, dark, futuristic | #00F0FF #FF0080 #0A0A0F |

npx @imehr/agentic-designer theme list
npx @imehr/agentic-designer theme apply stripe --dry-run
npx @imehr/agentic-designer theme create --from linear --name my-brand
npx @imehr/agentic-designer theme export --format css

DESIGN.md Format

Every project has a DESIGN.md in the repo root. It follows a 9-section format that agents read to understand the project's visual language.

| Section | Contents | |---------|----------| | 1. Identity | Name, version, base system, description | | 2. Color | Primary, secondary, accent, background, foreground, muted, destructive, border, input, ring | | 3. Typography | Font families, sizes, weights, line heights, letter spacing | | 4. Spacing | Scale with base unit and multipliers | | 5. Border Radius | Scale: none, sm, md, lg, full | | 6. Shadows | Scale: none, sm, md, lg, xl | | 7. Motion | Durations and easing functions | | 8. Icons | Provider (Lucide or Iconify), default set | | 9. Layout | Max width, grid, breakpoints |

The token-mapper module converts these sections into library-specific formats: CSS custom properties for shadcn, ConfigProvider tokens for Ant Design, and Tailwind theme extensions for Radix.

Multi-Platform Install

One skill works across all five supported agent platforms. The skill content is platform-agnostic; only the installation layer differs.

npx @imehr/agentic-designer install claude-code
npx @imehr/agentic-designer install codex
npx @imehr/agentic-designer install opencode
npx @imehr/agentic-designer install gemini-cli
npx @imehr/agentic-designer install copilot

| Platform | Skill Location | Config | |----------|---------------|--------| | Claude Code | .claude/skills/agentic-designer/ | .claude/settings.json | | Codex | ~/.codex/agents/agentic-designer/ | ~/.codex/config.json | | OpenCode | ~/.config/opencode/skills/agentic-designer/ | opencode.json | | Gemini CLI | ~/.gemini/extensions/agentic-designer/ | ~/.gemini/config.json | | GitHub Copilot | .github/copilot-instructions.md | .github/copilot-config.json |

Each install command copies skill files, registers hooks for self-correction, configures the sync daemon, and creates or updates DESIGN.md.

Project Structure

agentic-designer/
├── SKILL.md                          # Root skill definition loaded by agents
├── README.md
├── LICENSE                           # MIT
├── CONTRIBUTING.md
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── src/
│   ├── cli/
│   │   ├── index.ts                  # CLI entry point (commander)
│   │   └── commands/
│   │       ├── init.ts               # Project scaffolding
│   │       ├── generate.ts           # Component generation
│   │       ├── critique.ts           # 5D critique engine
│   │       ├── audit.ts              # Design violation auditor
│   │       ├── extract.ts            # Token extraction
│   │       ├── sync.ts               # Syncd daemon + sync status
│   │       ├── theme.ts              # Theme apply/create/list/export
│   │       ├── skill.ts              # Skill list/load/info
│   │       └── install.ts            # Platform installer
│   ├── core/
│   │   ├── types.ts                  # Shared type definitions
│   │   ├── catalog.ts                # Skill catalog parser
│   │   ├── critique-engine.ts        # 5D critique framework
│   │   ├── design-system.ts          # Design system resolution
│   │   ├── library-detector.ts       # Auto-detect shadcn/antd/radix
│   │   └── token-mapper.ts           # DESIGN.md -> library token format
│   └── scaffold/
│       └── templates/
│           └── next-shadcn/          # Next.js + shadcn template
│               ├── package.json
│               ├── tsconfig.json
│               ├── next.config.ts
│               ├── tailwind.config.ts
│               ├── components.json
│               ├── DESIGN.md
│               ├── start.sh
│               ├── app/
│               │   ├── layout.tsx
│               │   ├── page.tsx
│               │   └── globals.css
│               └── .claude/
│                   ├── settings.json
│                   └── skills/
│                       └── agentic-designer.md
├── skills/
│   ├── catalog.json                  # Skill index (31 entries)
│   ├── loader.js                     # Skill loading runtime
│   ├── web-prototype/SKILL.md
│   ├── dashboard/SKILL.md
│   ├── mobile-app/SKILL.md
│   ├── saas-landing/SKILL.md
│   ├── critique/SKILL.md
│   ├── pricing-page/SKILL.md
│   ├── docs-page/SKILL.md
│   ├── blog-post/SKILL.md
│   ├── email-marketing/SKILL.md
│   ├── social-carousel/SKILL.md
│   ├── mobile-onboarding/SKILL.md
│   ├── gamified-app/SKILL.md
│   ├── magazine-poster/SKILL.md
│   ├── motion-frames/SKILL.md
│   ├── sprite-animation/SKILL.md
│   ├── wireframe-sketch/SKILL.md
│   ├── tweaks/SKILL.md
│   ├── dating-web/SKILL.md
│   ├── digital-eguide/SKILL.md
│   ├── design-system/SKILL.md
│   ├── pm-spec/SKILL.md
│   ├── eng-runbook/SKILL.md
│   ├── finance-report/SKILL.md
│   ├── invoice/SKILL.md
│   ├── hr-onboarding/SKILL.md
│   ├── kanban-board/SKILL.md
│   ├── team-okrs/SKILL.md
│   ├── meeting-notes/SKILL.md
│   ├── simple-deck/SKILL.md
│   ├── guizang-ppt/SKILL.md
│   └── weekly-update/SKILL.md
├── design-systems/
│   ├── catalog.json                  # Design system index (11 entries)
│   ├── default/DESIGN.md
│   ├── linear/DESIGN.md
│   ├── stripe/DESIGN.md
│   ├── vercel/DESIGN.md
│   ├── apple/DESIGN.md
│   ├── anthropic/DESIGN.md
│   ├── supabase/DESIGN.md
│   ├── figma/DESIGN.md
│   ├── notion/DESIGN.md
│   ├── tesla/DESIGN.md
│   └── cyberpunk/DESIGN.md
├── component-libraries/
│   ├── shadcn/token-schema.json
│   ├── antd/token-schema.json
│   └── radix/token-schema.json
├── craft/
│   ├── accessibility.md
│   ├── anti-ai-slop.md
│   ├── color.md
│   ├── layout.md
│   ├── responsive.md
│   └── typography.md
├── philosophy/
│   ├── 20-philosophies.md
│   ├── 5-directions.md
│   ├── brand-protocol.md
│   ├── junior-designer-workflow.md
│   └── self-critique.md
├── agents/
│   ├── accessibility-auditor.md
│   ├── brand-guardian.md
│   ├── design-critic.md
│   └── ux-reviewer.md
├── hooks/
│   ├── critique.js
│   ├── post-tool-use.sh
│   └── pre-commit.sh
├── docs/
│   ├── architecture.md
│   ├── cli-reference.md
│   ├── component-library-bridge.md
│   ├── design-system-schema.md
│   ├── skills-protocol.md
│   └── sync-protocol.md
└── tests/
    ├── cli/
    │   ├── index.test.ts
    │   └── commands/
    │       ├── init.test.ts
    │       ├── generate.test.ts
    │       ├── critique.test.ts
    │       ├── audit.test.ts
    │       ├── extract.test.ts
    │       ├── sync.test.ts
    │       ├── theme.test.ts
    │       ├── skill.test.ts
    │       └── install.test.ts
    ├── core/
    │   ├── catalog.test.ts
    │   ├── critique-engine.test.ts
    │   ├── design-system.test.ts
    │   ├── library-detector.test.ts
    │   └── token-mapper.test.ts
    └── fixtures/
        ├── sample-catalog.json
        ├── sample-design.md
        ├── minimal-design.md
        ├── sample-component.tsx
        ├── bad-component.tsx
        ├── empty-component.tsx
        └── craft/
            └── typography.md

Development

npm install
npm test          # 153 tests across 17 files
npm run check     # typecheck + lint + test
npm run build     # compile to dist/

Requires Node.js >= 18.

Lineage

agentic-designer is built on foundations from three open-source projects:

Huashu-Design -- the design quality compass. Contributed the 20 design philosophies, 5D critique framework, anti-slop checklist, Junior Designer workflow, and brand protocol.

Open Design -- the design intelligence architecture. Contributed the DESIGN.md format, skill catalog protocol, craft references, and direction picker system.

agentic-designer -- the tooling. Built the CLI, component library bridge, sync daemon, scaffold templates, and multi-platform installer that make the design intelligence accessible to any coding agent.

License

MIT -- Copyright 2025 Mehran Mozaffari.