How oil-oil/ui-ux-guide works
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: SKILL.md SKILL.md · index.md Style index · design-preview-template.html Preview · design-spec-template.md Design spec
Components 22
Adapters
Entry points that bridge the shared behavior into different agent environments.
- AGENTS.md · Common instruction hub for agent runtimes.
AGENTS.md - CLAUDE.md · Claude-specific entrypoint into the shared skill behavior.
CLAUDE.md - Cursor rule · Cursor rule file that loads the shared guidance into the editor agent.
.cursor/rules/oiloil-ui-ux-guide.mdc - OpenAI meta · OpenAI/Codex-style installation metadata for the skill.
agents/openai.yaml
Core skill
Canonical behavior definition for the UI/UX consulting skill.
- SKILL.md · Primary behavior contract for design, guide, and review modes.
skills/oiloil-ui-ux-guide/SKILL.md - Modes · Design, guide, and review mode behavior and output shape.
skills/oiloil-ui-ux-guide/SKILL.md - Design flow · Repo scan, interview, style selection, token choices, previewing, and spec writing.
skills/oiloil-ui-ux-guide/SKILL.md - Review flow · Prioritized UI critique with fixes and recommendations.
skills/oiloil-ui-ux-guide/SKILL.md - Guide flow · 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 · Cross-project hard rules for interaction and design quality.
skills/oiloil-ui-ux-guide/references/system-principles.md - Interaction psych · Conversation and user-intent psychology for guiding design decisions.
skills/oiloil-ui-ux-guide/references/interaction-psychology.md - Design psych · Design-psychology language used to frame critique and recommendations.
skills/oiloil-ui-ux-guide/references/design-psych.md - Checklists · Reusable review and completion checklists.
skills/oiloil-ui-ux-guide/references/checklists.md - Templates · Structures for design specs, reviews, contracts, and related outputs.
skills/oiloil-ui-ux-guide/references/design-spec-template.md - Style index · Entry point for selectable style families.
skills/oiloil-ui-ux-guide/references/style-families/index.md - Style families · Selectable visual directions such as editorial, brutal, modern minimal, and others.
skills/oiloil-ui-ux-guide/references/style-families/modern-minimal.md - 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 · 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 · Browser-based compare/full preview surface for token and layout feedback.
skills/oiloil-ui-ux-guide/references/design-preview-template.html - Design spec · Project-specific design specification written into the target repository.
skills/oiloil-ui-ux-guide/references/design-spec-template.md - README · Human-facing installation and usage guide.
README.md - index.html · Simple landing or description page for the skill.
index.html
Connections 22
- 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.