# oil-oil/ui-ux-guide architecture

> Architecture diagram of the GitHub repository oil-oil/ui-ux-guide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oil-oil/ui-ux-guide
- Repository: https://github.com/oil-oil/ui-ux-guide

## Overview

1. **Repository purpose**
   - This is not a product app; it is a **cross-agent UI/UX consulting Skill** package.
   - The repo’s job is to standardize how an AI assistant conducts design interviews, produces design specs, reviews UIs, and generates rule sets.

2. **Top-level architecture**
   - The repository is organized around a **single source of behavior** plus **adapter files** for different AI tools.
   - Core logic lives under `skills/oiloil-ui-ux-guide/`.
   - Surrounding files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*`, `agents/openai.yaml`) act as **entrypoint bridges** into that same behavior.

3. **Primary behavior definition**
   - `skills/oiloil-ui-ux-guide/SKILL.md` is the canonical spec for the Skill.
   - It defines the three operating modes: `design`, `guide`, and `review`.
   - It also defines the interaction contract: silent code scan first in `design`, then conversation, then output.

4. **Mode-based workflow boundary**
   - `design` is the most stateful flow: it starts with repository inspection, then progresses through interviewing, style-family selection, token choices, previewing, and finally writing `design-spec.md`.
   - `guide` is a lightweight rule-generation mode for a page type.
   - `review` is an audit mode that produces prioritized issues and fixes.
   - These modes are a major architectural boundary because they determine output shape and conversational behavior.

5. **Knowledge base / reference layer**
   - `skills/oiloil-ui-ux-guide/references/` is the reusable knowledge layer.
   - It contains:
     - system-level principles,
     - interaction psychology,
     - design psychology vocabulary,
     - icon rules,
     - checklists,
     - output templates,
     - and style-family definitions.
   - This layer is what turns the Skill from a generic chat prompt into a structured methodology.

6. **Style system boundary**
   - The repo explicitly separates **UX hard rules** from **style families**.
   - Hard rules are treated as cross-project, non-negotiable interaction principles.
   - Style families under `references/style-families/` are selectable visual lenses, not defaults.
   - This separation is central to the architecture: it prevents a single aesthetic from being baked into all projects.

7. **Design output pipeline**
   - The design flow is meant to converge on a project-specific artifact: `design-spec.md` in the target repository.
   - `references/design-spec-template.md` provides the structure of that output.
   - This means the Skill is effectively a **spec-generation system**, not just advice.

8. **Preview / feedback loop**
   - `references/design-preview-template.html` is a static browser-based preview surface.
   - It supports compare and full modes, with multiple face types and viewport/dark-mode switching.
   - Architecturally, this is the visual feedback loop between abstract token decisions and concrete UI previews.

9. **Evaluation and regression checking**
   - `skills/oiloil-ui-ux-guide/evals/evals.json` contains test cases for the Skill behavior.
   - This acts as a quality gate for prompt/system consistency, not application logic.
   - The evals are important because the repo’s “correctness” is mostly behavioral: whether the Skill asks, recommends, and critiques in the intended way.

10. **Multi-agent integration layer**
   - `AGENTS.md` is the shared instruction hub.
   - `CLAUDE.md` and `.cursor/rules/oiloil-ui-ux-guide.mdc` bridge that shared guidance into specific tools.
   - `agents/openai.yaml` describes metadata for OpenAI/Codex-style Skill installation.
   - The architecture here is adapter-based: one behavioral core, multiple agent-specific entrypoints.

11. **Documentation and distribution surface**
   - `README.md` is the human-facing overview and installation guide.
   - `index.html` acts as a simple landing/description page for the Skill.
   - The repo is designed to be installed or copied into agent environments, so documentation is part of the runtime boundary.

12. **Runtime shape**
   - There is no backend service, database, or build pipeline in the usual application sense.
   - The “runtime” is the AI agent plus its surrounding instruction context, reference files, and optional browser preview template.
   - The only executed artifact in the repo is the static HTML preview; the rest is prompt/knowledge configuration.

13. **Important architectural takeaway**
   - Think of this repo as a **prompt-driven design system toolkit**:
     - adapters load it,
     - `SKILL.md` defines behavior,
     - `references/` supply doctrine,
     - `evals/` validate behavior,
     - and the preview template closes the loop with visual confirmation.

Main entry points: [`skills/oiloil-ui-ux-guide/SKILL.md`](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md) (SKILL.md), [`skills/oiloil-ui-ux-guide/references/style-families/index.md`](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/style-families/index.md) (Style index), [`skills/oiloil-ui-ux-guide/references/design-preview-template.html`](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/design-preview-template.html) (Preview), [`skills/oiloil-ui-ux-guide/references/design-spec-template.md`](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/design-spec-template.md) (Design spec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_adapters["Adapters"]
  node_node_agents_md["AGENTS.md<br/>shared instructions<br/>[AGENTS.md]"]
  node_node_claude_md["CLAUDE.md<br/>claude bridge<br/>[CLAUDE.md]"]
  node_node_cursor_rule["Cursor rule<br/>cursor bridge"]
  node_node_openai_yaml["OpenAI meta<br/>skill metadata<br/>[openai.yaml]"]
end

subgraph group_group_core["Core skill"]
  node_node_skill_md["SKILL.md<br/>canonical spec<br/>[SKILL.md]"]
  node_node_modes{{"Modes<br/>workflow boundary<br/>[SKILL.md]"}}
  node_node_design_flow["Design flow<br/>stateful workflow<br/>[SKILL.md]"]
  node_node_review_flow["Review flow<br/>audit workflow<br/>[SKILL.md]"]
  node_node_guide_flow["Guide flow<br/>rule generator<br/>[SKILL.md]"]
end

subgraph group_group_references["References"]
  node_node_principles["Principles<br/>ux doctrine"]
  node_node_interaction_psych["Interaction psych<br/>behavior model"]
  node_node_design_psych["Design psych<br/>vocabulary<br/>[design-psych.md]"]
  node_node_checklists["Checklists<br/>quality checks<br/>[checklists.md]"]
  node_node_templates["Templates"]
  node_node_style_index["Style index<br/>style catalog<br/>[index.md]"]
  node_node_style_families["Style families<br/>visual lenses<br/>[modern-minimal.md]"]
  node_node_business_contract["Contract"]
end

subgraph group_group_evals["Evals"]
  node_node_evals_json["Evals<br/>behavior tests<br/>[evals.json]"]
end

subgraph group_group_outputs["Outputs"]
  node_node_preview_html["Preview<br/>static html"]
  node_node_design_spec["Design spec<br/>target artifact"]
  node_node_readme["README<br/>overview docs<br/>[README.md]"]
  node_node_index_html["index.html<br/>landing page<br/>[index.html]"]
end

node_node_agents_md -->|"loads"| node_node_skill_md
node_node_claude_md -->|"bridges"| node_node_skill_md
node_node_cursor_rule -->|"bridges"| node_node_skill_md
node_node_openai_yaml -->|"installs"| node_node_skill_md
node_node_skill_md -->|"defines"| node_node_modes
node_node_modes -->|"includes"| node_node_design_flow
node_node_modes -->|"includes"| node_node_review_flow
node_node_modes -->|"includes"| node_node_guide_flow
node_node_skill_md -->|"depends on"| node_node_principles
node_node_skill_md -->|"depends on"| node_node_interaction_psych
node_node_skill_md -->|"formats output with"| node_node_templates
node_node_skill_md -->|"references"| node_node_style_index
node_node_style_index -->|"catalogs"| node_node_style_families
node_node_skill_md -->|"uses"| node_node_checklists
node_node_skill_md -->|"uses"| node_node_design_psych
node_node_skill_md -.->|"anchors"| node_node_business_contract
node_node_design_flow -->|"feedback loop"| node_node_preview_html
node_node_design_flow -->|"writes"| node_node_design_spec
node_node_preview_html -.->|"informs"| node_node_design_spec
node_node_evals_json -->|"validates"| node_node_skill_md
node_node_readme -->|"documents"| node_node_skill_md
node_node_index_html -->|"describes"| node_node_skill_md

click node_node_agents_md "https://github.com/oil-oil/ui-ux-guide/blob/main/AGENTS.md"
click node_node_claude_md "https://github.com/oil-oil/ui-ux-guide/blob/main/CLAUDE.md"
click node_node_cursor_rule "https://github.com/oil-oil/ui-ux-guide/blob/main/.cursor/rules/oiloil-ui-ux-guide.mdc"
click node_node_openai_yaml "https://github.com/oil-oil/ui-ux-guide/blob/main/agents/openai.yaml"
click node_node_skill_md "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md"
click node_node_modes "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md"
click node_node_design_flow "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md"
click node_node_review_flow "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md"
click node_node_guide_flow "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md"
click node_node_principles "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/system-principles.md"
click node_node_interaction_psych "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/interaction-psychology.md"
click node_node_design_psych "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/design-psych.md"
click node_node_checklists "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/checklists.md"
click node_node_templates "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/design-spec-template.md"
click node_node_style_index "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/style-families/index.md"
click node_node_style_families "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/style-families/modern-minimal.md"
click node_node_business_contract "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/business-mockup-contract.md"
click node_node_preview_html "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/design-preview-template.html"
click node_node_design_spec "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/design-spec-template.md"
click node_node_evals_json "https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/evals/evals.json"
click node_node_readme "https://github.com/oil-oil/ui-ux-guide/blob/main/README.md"
click node_node_index_html "https://github.com/oil-oil/ui-ux-guide/blob/main/index.html"

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_node_agents_md,node_node_claude_md,node_node_cursor_rule,node_node_openai_yaml toneBlue
class node_node_skill_md,node_node_modes,node_node_design_flow,node_node_review_flow,node_node_guide_flow toneAmber
class node_node_principles,node_node_interaction_psych,node_node_design_psych,node_node_checklists,node_node_templates,node_node_style_index,node_node_style_families,node_node_business_contract toneMint
class node_node_evals_json toneRose
class node_node_preview_html,node_node_design_spec,node_node_readme,node_node_index_html toneIndigo
```

## Components

### Adapters

Entry points that bridge the shared behavior into different agent environments.

- [AGENTS.md](https://github.com/oil-oil/ui-ux-guide/blob/main/AGENTS.md): shared instructions · Common instruction hub for agent runtimes. · `AGENTS.md`
- [CLAUDE.md](https://github.com/oil-oil/ui-ux-guide/blob/main/CLAUDE.md): claude bridge · Claude-specific entrypoint into the shared skill behavior. · `CLAUDE.md`
- [Cursor rule](https://github.com/oil-oil/ui-ux-guide/blob/main/.cursor/rules/oiloil-ui-ux-guide.mdc): cursor bridge · Cursor rule file that loads the shared guidance into the editor agent. · `.cursor/rules/oiloil-ui-ux-guide.mdc`
- [OpenAI meta](https://github.com/oil-oil/ui-ux-guide/blob/main/agents/openai.yaml): skill metadata · OpenAI/Codex-style installation metadata for the skill. · `agents/openai.yaml`

### Core skill

Canonical behavior definition for the UI/UX consulting skill.

- [SKILL.md](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md): canonical spec · Primary behavior contract for design, guide, and review modes. · `skills/oiloil-ui-ux-guide/SKILL.md`
- [Modes](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md): workflow boundary · Design, guide, and review mode behavior and output shape. · `skills/oiloil-ui-ux-guide/SKILL.md`
- [Design flow](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md): stateful workflow · Repo scan, interview, style selection, token choices, previewing, and spec writing. · `skills/oiloil-ui-ux-guide/SKILL.md`
- [Review flow](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md): audit workflow · Prioritized UI critique with fixes and recommendations. · `skills/oiloil-ui-ux-guide/SKILL.md`
- [Guide flow](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/SKILL.md): rule generator · Lightweight mode for generating page-type guidance and rules. · `skills/oiloil-ui-ux-guide/SKILL.md`

### References

Reusable doctrine, templates, and style-family knowledge used by the skill.

- [Principles](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/system-principles.md): ux doctrine · Cross-project hard rules for interaction and design quality. · `skills/oiloil-ui-ux-guide/references/system-principles.md`
- [Interaction psych](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/interaction-psychology.md): behavior model · Conversation and user-intent psychology for guiding design decisions. · `skills/oiloil-ui-ux-guide/references/interaction-psychology.md`
- [Design psych](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/design-psych.md): vocabulary · Design-psychology language used to frame critique and recommendations. · `skills/oiloil-ui-ux-guide/references/design-psych.md`
- [Checklists](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/checklists.md): quality checks · Reusable review and completion checklists. · `skills/oiloil-ui-ux-guide/references/checklists.md`
- [Templates](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/design-spec-template.md): output templates · Structures for design specs, reviews, contracts, and related outputs. · `skills/oiloil-ui-ux-guide/references/design-spec-template.md`
- [Style index](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/style-families/index.md): style catalog · Entry point for selectable style families. · `skills/oiloil-ui-ux-guide/references/style-families/index.md`
- [Style families](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/style-families/modern-minimal.md): visual lenses · Selectable visual directions such as editorial, brutal, modern minimal, and others. · `skills/oiloil-ui-ux-guide/references/style-families/modern-minimal.md`
- [Contract](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/business-mockup-contract.md): scope contract · Business/mockup agreement used to anchor the design engagement. · `skills/oiloil-ui-ux-guide/references/business-mockup-contract.md`

### Evals

Behavioral checks that validate the skill's intended interaction patterns.

- [Evals](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/evals/evals.json): behavior tests · Test cases that validate prompts, recommendations, and critique behavior. · `skills/oiloil-ui-ux-guide/evals/evals.json`

### Outputs

Artifacts and surfaces produced or supported by the skill.

- [Preview](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/design-preview-template.html): static html · Browser-based compare/full preview surface for token and layout feedback. · `skills/oiloil-ui-ux-guide/references/design-preview-template.html`
- [Design spec](https://github.com/oil-oil/ui-ux-guide/blob/main/skills/oiloil-ui-ux-guide/references/design-spec-template.md): target artifact · Project-specific design specification written into the target repository. · `skills/oiloil-ui-ux-guide/references/design-spec-template.md`
- [README](https://github.com/oil-oil/ui-ux-guide/blob/main/README.md): overview docs · Human-facing installation and usage guide. · `README.md`
- [index.html](https://github.com/oil-oil/ui-ux-guide/blob/main/index.html): landing page · Simple landing or description page for the skill. · `index.html`

## Connections

- AGENTS.md → SKILL.md: loads · Shared instructions route agents into the canonical skill spec.
- CLAUDE.md → SKILL.md: bridges · Claude entrypoint forwards into the common behavior definition.
- Cursor rule → SKILL.md: bridges · Cursor rule delegates to the canonical skill contract.
- OpenAI meta → SKILL.md: installs · Metadata describes the skill for OpenAI/Codex-style environments.
- SKILL.md → Modes: defines · Canonical spec establishes the operating modes and their contracts.
- Modes → Design flow: includes · Design is the most stateful mode and drives repository inspection to spec output.
- Modes → Review flow: includes · Review mode produces prioritized findings and fixes.
- Modes → Guide flow: includes · Guide mode generates page-type rule sets.
- SKILL.md → Principles: depends on · Behavior is grounded in cross-project UX principles.
- SKILL.md → Interaction psych: depends on · Conversation and interview structure use interaction psychology.
- SKILL.md → Templates: formats output with · Skill outputs are shaped by reusable templates.
- SKILL.md → Style index: references · Skill exposes style families through the index layer.
- Style index → Style families: catalogs · Index points to the selectable style-family definitions.
- SKILL.md → Checklists: uses · Checklists support design completion and review consistency.
- SKILL.md → Design psych: uses · Critique and recommendation language draw from design-psych vocabulary.
- SKILL.md → Contract: anchors · Contract layer helps scope the design engagement.
- Design flow → Preview: feedback loop · Token and layout choices are validated in the preview surface.
- Design flow → Design spec: writes · Design flow converges on a project-specific spec artifact.
- Preview → Design spec: informs · Preview supports the spec-writing decision loop.
- Evals → SKILL.md: validates · Behavioral tests check that the skill follows its intended interaction contract.
- README → SKILL.md: documents · README explains how to use and install the skill.
- index.html → SKILL.md: describes · Landing page presents the skill as a distributable package.