ui-agent-patterns

UI エージェントのパターン

ユーザーインターフェースの生成、改善、保守を行う AI エージェントをオーケストレーションするためのパターンです。Karpathy の「新しいプログラミングの語彙」と、実践的な UI/UX 開発ワークフローをつなぎます。

---

このスキルを使う場面

• 複雑な UI 生成を専門エージェントに委任する
• 合成マスター型と専門エージェント型のアーキテクチャのどちらを選ぶか判断する
• デザインシステム向けのマルチエージェントワークフローをオーケストレーションする
• リサーチ、デザイン、実装を担当するエージェント間の引き継ぎを管理する
• UI を反復的に改善するためのエージェントパイプラインを構築する
• 単一エージェントの能力を超えて UI 生成を拡張する

---

基本概念

新しいプログラミングの語彙

Karpathy の洞察：LLM によって、関数やオブジェクトを超える新しいプログラミングプリミティブが登場しました。

プリミティブ	説明	UI での活用
エージェント	LLM を活用する自律型ワーカー	UI 生成、レビュー、改善
サブエージェント	委任された専門家	コンポーネントの構築、アクセシビリティの確認
プロンプト	コードとしての指示	デザイン仕様、コンポーネントの契約
コンテキスト	共有される状態と知識	デザイントークン、ブランドガイドライン
メモリ	永続的な学習内容	スタイルの好み、過去の決定
モード	動作の設定	ドラフトモード、本番モード、監査モード
権限	能力の境界	読み取り専用レビューとコード変更の区別
ツール	外部機能	Figma API、ブラウザーの DevTools、スクリーンショットの取得
プラグイン	モジュール式の拡張機能	デザインシステムローダー、コンポーネントライブラリ
スキル	再利用可能な知識	このファイルに体系化された専門知識
フック	ライフサイクルのインターセプター	コミット前のデザインチェック、レンダリング後の監査
MCP	Model Context Protocol	ツール統合標準
ワークフロー	オーケストレーションされた一連の処理	デザインからコードへのパイプライン

---

エージェントアーキテクチャのパターン

パターン 1：合成マスター型アーキテクチャ

単一の高性能エージェントが、UI 生成タスク全体を処理します。

使用する場面：

• シンプルで明確に定義された UI タスク
• 意思決定間の結びつきが強い
• スピードが重要
• タスク全体に十分なコンテキストウィンドウがある

構造：

[User Request]
      |
      v
+------------------+
|  Synthesis-Master |
|  (Full Context)  |
+------------------+
      |
      v
[Complete UI Output]

実装：

class SynthesisMasterAgent:
    """
    Single agent handling all UI generation aspects.
    Best for: Landing pages, simple forms, atomic components
    """

    def __init__(self, model: str = "claude-sonnet-4-5-20250929"):
        self.context = {
            "design_tokens": load_design_tokens(),
            "brand_guidelines": load_brand_context(),
            "component_library": load_component_docs(),
            "accessibility_rules": load_a11y_rules(),
        }

    async def generate(self, request: UIRequest) -> UIOutput:
        prompt = f"""
        You are a senior UI engineer and designer. Generate a complete,
        production-ready component based on this request.

        Context:
        - Design Tokens: {self.context['design_tokens']}
        - Brand Guidelines: {self.context['brand_guidelines']}

        Request: {request.description}

        Output requirements:
        1. React/TypeScript component
        2. Tailwind CSS styling
        3. Accessibility attributes
        4. Responsive breakpoints
        5. Dark mode support
        """

        return await self.model.generate(prompt)

利点：

• オーケストレーションがよりシンプル
• 引き継ぎに伴うオーバーヘッドがない
• 一貫した語り口とスタイル
• レイテンシが低い

欠点：

• コンテキストウィンドウの制限
• 単一障害点
• 複雑さへの対応が難しい
• 専門知識を活用できない

---

パターン 2：専門エージェントの群れ

複数の専門エージェントが UI タスクで協力します。

使用する場面：

• 複雑なデザインシステム
• 異なる専門知識を必要とするタスク
• 並列処理が有効
• 専門化によって品質を高めたい

構造：

[User Request]
      |
      v
+------------------+
|   Orchestrator   |
+------------------+
      |
      +-----------------+----------------+----------------+
      |                 |                |                |
      v                 v                v                v
+----------+     +----------+     +----------+     +----------+
| Research |     |  Design  |     |   Code   |     |  Review  |
|  Agent   |     |  Agent   |     |  Agent   |     |  Agent   |
+----------+     +----------+     +----------+     +----------+
      |                 |                |                |
      v                 v                v                v
  [Context]        [Wireframe]      [Component]       [Audit]

専門エージェントの定義：

# Agent 1: Research Agent
class UIResearchAgent:
    """
    Gathers context and prior art before design begins.
    """

    permissions = ["read_codebase", "search_web", "read_figma"]

    async def research(self, request: UIRequest) -> ResearchContext:
        return {
            "existing_patterns": await self.find_similar_components(),
            "competitive_analysis": await self.analyze_competitors(),
            "user_research": await self.gather_user_insights(),
            "technical_constraints": await self.identify_constraints(),
        }

# Agent 2: Design Agent
class UIDesignAgent:
    """
    Produces design specifications and wireframes.
    """

    permissions = ["generate_images", "access_design_tokens"]

    async def design(self, context: ResearchContext) -> DesignSpec:
        return {
            "layout": await self.generate_layout(),
            "spacing": await self.calculate_spacing(),
            "typography": await self.select_typography(),
            "colors": await self.derive_color_scheme(),
            "interactions": await self.define_interactions(),
        }

# Agent 3: Implementation Agent
class UIImplementationAgent:
    """
    Translates designs into production code.
    """

    permissions = ["write_code", "access_component_library"]

    async def implement(self, spec: DesignSpec) -> CodeOutput:
        return await self.generate_component(
            framework="react",
            styling="tailwind",
            typescript=True,
            spec=spec
        )

# Agent 4: Review Agent
class UIReviewAgent:
    """
    Audits output for quality, accessibility, and standards.
    """

    permissions = ["read_code", "run_tests", "access_browser"]
    mode = "audit"  # Read-only, cannot modify

    async def review(self, code: CodeOutput) -> ReviewReport:
        return {
            "accessibility": await self.audit_a11y(),
            "performance": await self.audit_performance(),
            "design_fidelity": await self.compare_to_spec(),
            "code_quality": await self.lint_and_analyze(),
        }

---

パターン 3：階層型の委任

マスターエージェントが、特定のサブタスクをサブエージェントに委任します。

使用する場面：

• コンポーネントが多い複雑なページ
• コンポーネント生成の並列化が必要
• コンポーネントごとに異なる専門知識が必要

構造：

[User Request: "Create a dashboard"]
             |
             v
    +------------------+
    |   Master Agent   |
    | (Task Planning)  |
    +------------------+
             |
    +--------+--------+--------+
    |        |        |        |
    v        v        v        v
[Header] [Sidebar] [Charts] [Tables]
Subagent Subagent Subagent Subagent
    |        |        |        |
    v        v        v        v
  [JSX]    [JSX]    [JSX]    [JSX]
             |
             v
    +------------------+
    |   Master Agent   |
    |  (Integration)   |
    +------------------+
             |
             v
     [Complete Dashboard]

実装：

class HierarchicalUIOrchestrator:
    """
    Master agent that delegates to specialized subagents.
    """

    def __init__(self):
        self.subagents = {
            "header": HeaderComponentAgent(),
            "sidebar": SidebarComponentAgent(),
            "charts": DataVisualizationAgent(),
            "tables": DataTableAgent(),
            "forms": FormBuilderAgent(),
        }

    async def generate_page(self, request: PageRequest) -> PageOutput:
        # Step 1: Plan the page structure
        plan = await self.plan_page_structure(request)

        # Step 2: Delegate component generation in parallel
        component_tasks = []
        for component in plan.components:
            agent = self.subagents[component.type]
            task = agent.generate(component.spec)
            component_tasks.append(task)

        components = await asyncio.gather(*component_tasks)

        # Step 3: Integrate components into cohesive page
        page = await self.integrate_components(components, plan.layout)

        # Step 4: Final coherence review
        return await self.ensure_coherence(page)

    async def plan_page_structure(self, request: PageRequest) -> PagePlan:
        """
        Master agent determines page structure and delegation.
        """
        prompt = f"""
        Analyze this page request and create a component breakdown:

        Request: {request.description}

        For each component, specify:
        1. Component type (header, sidebar, chart, table, form, etc.)
        2. Component requirements
        3. Data dependencies
        4. Layout position

        Return as structured JSON.
        """
        return await self.model.generate(prompt, format="json")

---

マルチエージェントワークフローのパターン

ワークフロー 1：デザインからコードへのパイプライン

デザインの意図から本番コードまでを順に進めるワークフローです。

class DesignToCodePipeline:
    """
    Complete workflow from natural language to deployed UI.
    """

    stages = [
        ("interpret", InterpretationAgent()),    # NL -> Design Intent
        ("design", DesignAgent()),               # Intent -> Wireframe
        ("specify", SpecificationAgent()),       # Wireframe -> Spec
        ("implement", ImplementationAgent()),    # Spec -> Code
        ("review", ReviewAgent()),               # Code -> Audit
        ("refine", RefinementAgent()),           # Audit -> Final Code
    ]

    async def run(self, request: str) -> CodeOutput:
        context = {"request": request}

        for stage_name, agent in self.stages:
            result = await agent.process(context)
            context[stage_name] = result

            # Allow early exit on critical issues
            if result.has_blocking_issues:
                return self.handle_blocker(stage_name, result)

        return context["refine"]

ワークフロー 2：反復改善ループ

複数回のパスを通じて UI を改善するエージェントループです。

class IterativeRefinementWorkflow:
    """
    Generate -> Review -> Refine loop until quality threshold met.
    """

    def __init__(self, max_iterations: int = 5):
        self.generator = UIGeneratorAgent()
        self.reviewer = UIReviewerAgent()
        self.refiner = UIRefinerAgent()
        self.max_iterations = max_iterations
        self.quality_threshold = 0.85

    async def run(self, request: UIRequest) -> RefinedOutput:
        # Initial generation
        current = await self.generator.generate(request)

        for iteration in range(self.max_iterations):
            # Review current version
            review = await self.reviewer.review(current)

            # Check if quality threshold met
            if review.score >= self.quality_threshold:
                return current

            # Refine based on feedback
            current = await self.refiner.refine(
                current=current,
                feedback=review.feedback,
                priority=review.critical_issues
            )

        # Return best effort after max iterations
        return current

ワークフロー 3：バリエーションの並列生成

比較できるように、複数のデザインバリエーションを生成します。

class ParallelVariantWorkflow:
    """
    Generate multiple design variants in parallel for A/B consideration.
    """

    async def generate_variants(
        self,
        request: UIRequest,
        variant_count: int = 3
    ) -> list[DesignVariant]:

        # Define variant strategies
        strategies = [
            {"style": "minimal", "focus": "whitespace"},
            {"style": "bold", "focus": "typography"},
            {"style": "playful", "focus": "interactions"},
        ][:variant_count]

        # Generate in parallel
        tasks = [
            self.generate_variant(request, strategy)
            for strategy in strategies
        ]

        variants = await asyncio.gather(*tasks)

        # Score and rank variants
        scored = await self.score_variants(variants, request.criteria)

        return sorted(scored, key=lambda v: v.score, reverse=True)

---

エージェントメモリのパターン

パターン：デザイン決定のメモリ

セッションをまたいで一貫性を保つため、デザインに関する決定を永続化します。

class DesignMemory:
    """
    Persistent memory of design decisions and preferences.
    """

    def __init__(self, project_id: str):
        self.project_id = project_id
        self.decisions = self.load_decisions()

    def remember_decision(self, decision: DesignDecision):
        """
        Store a design decision for future reference.

        Example decisions:
        - "Primary buttons use bg-blue-600, not bg-blue-500"
        - "Card corners are rounded-xl (12px)"
        - "Error states use red-600 with shake animation"
        """
        self.decisions.append({
            "timestamp": datetime.now(),
            "category": decision.category,
            "rule": decision.rule,
            "rationale": decision.rationale,
        })
        self.persist()

    def recall_relevant(self, context: str) -> list[DesignDecision]:
        """
        Retrieve decisions relevant to current context.
        """
        # Semantic search over past decisions
        return self.vector_search(context, top_k=5)

    def inject_into_prompt(self, base_prompt: str) -> str:
        """
        Augment prompt with relevant past decisions.
        """
        relevant = self.recall_relevant(base_prompt)

        if not relevant:
            return base_prompt

        decisions_context = "\n".join([
            f"- {d.rule} (Rationale: {d.rationale})"
            for d in relevant
        ])

        return f"""
        {base_prompt}

        ## Past Design Decisions (maintain consistency):
        {decisions_context}
        """

---

モードと権限

エージェントのモード

さまざまな状況に合わせてエージェントの動作を設定します。

class UIAgentModes:
    """
    Different operational modes for UI agents.
    """

    MODES = {
        "draft": {
            "description": "Fast, exploratory generation",
            "quality_threshold": 0.6,
            "iterations": 1,
            "include_comments": True,
            "placeholder_content": True,
        },
        "production": {
            "description": "High-quality, deployment-ready",
            "quality_threshold": 0.9,
            "iterations": 5,
            "include_comments": False,
            "placeholder_content": False,
        },
        "audit": {
            "description": "Read-only review mode",
            "can_modify": False,
            "generate_report": True,
        },
        "learning": {
            "description": "Explain decisions, teach patterns",
            "verbose_reasoning": True,
            "cite_sources": True,
        },
    }

権限の境界

エージェントに許可する操作と許可しない操作を定義します。

class AgentPermissions:
    """
    Capability boundaries for UI agents.
    """

    # File system permissions
    READ_CODEBASE = "read_codebase"
    WRITE_COMPONENTS = "write_components"
    WRITE_STYLES = "write_styles"
    MODIFY_CONFIG = "modify_config"

    # Tool permissions
    ACCESS_BROWSER = "access_browser"
    ACCESS_FIGMA = "access_figma"
    RUN_TESTS = "run_tests"
    DEPLOY_PREVIEW = "deploy_preview"

    # Common permission sets
    READONLY_REVIEWER = [READ_CODEBASE, ACCESS_BROWSER]
    COMPONENT_BUILDER = [READ_CODEBASE, WRITE_COMPONENTS, WRITE_STYLES]
    FULL_ACCESS = [READ_CODEBASE, WRITE_COMPONENTS, WRITE_STYLES,
                   MODIFY_CONFIG, ACCESS_BROWSER, RUN_TESTS]

---

避けるべきアンチパターン

1. 巨大なモノリシックプロンプト

問題：すべての指示を 1 つの巨大なプロンプトに詰め込むこと 解決策：焦点を絞ったエージェントを使い、階層的に委任する

2. コンテキストのオーバーフロー

問題: デザインシステム全体を扱うことでコンテキストウィンドウを超過します 解決策: RAG を使って、関連するコンテキストを動的に注入します

3. フィードバックループがない

問題: 検証を行わず、1 回の生成で完了します 解決策: 品質のしきい値を設けて、レビューと改善を繰り返すループを実装します

4. ワークフローがハードコードされている

問題: 柔軟に適応できない固定的なパイプラインです 解決策: タスクの複雑さに応じた動的なオーケストレーションを行います

5. エージェントの無秩序な状態

問題: 担当範囲が不明確なエージェントが多すぎます 解決策: 明確な関心領域の分離と、明示的な引き継ぎプロトコルを設けます

---

クイックリファレンス

シナリオ	推奨パターン
シンプルなコンポーネント	Synthesis-Master
ページ全体のデザイン	階層的な委任
デザインシステムの作業	専門エージェントの群
迅速なプロトタイピング	ドラフトモード＋単一エージェント
本番環境へのデプロイ	レビューを含む完全なパイプライン
デザインの A/B テスト	バリアントの並列生成

---

LibreUIUX との統合

このスキルは、以下と組み合わせると最も効果的です：

• design-mastery/design-principles - 原則を Design Agent に渡します
• archetypal-alchemy/jungian-archetypes - UI 生成に個性を加えます
• context-management/design-system-context - トークンを管理します
• mcp-integrations/browser-devtools-mcp - ライブ検査ツール

---

"エージェントはコードではなく、実行可能になった意図です。"