For independent developers and small teams, without a dedicated designer

Design Decision Method

A lightweight workflow for people and AI agents to decide what a screen needs, how to organize it, and which interactions and visual direction fit, before drawing or coding.

Get started View on GitHub

Where it fits. An agent builds the interface, and you keep correcting what it shows and how the flow works.

Release 2.2.4. Licensed under the MIT License.

What it is for

It draws on established guidance. It does not create another UI library or visual standard.

It addresses repeated UI guesswork: starting from a generic layout, overlooking information the screen needs, adding complexity that does not help the task, and making the same decisions again on the next project.

Consequential choices are written down before building.

The reason to keep it is a shared approach across products and agents: simple to understand, informative enough to decide, and efficient to use, without explaining that approach from scratch each time.

Whether it saves time has not been measured.

It is a shared procedure. It is not mandatory for every small edit.

How it works

These six steps are the workflow in SKILL.md, in the same order.

The agent procedure routes UI work across OOUX object mapping, GOV.UK, Carbon, Material 3, platform guidelines, and a project's own rules. It does not rank those sources, copy their branding, or claim research or compliance it has not done.

If guidance conflicts, resolve it from the project: accessibility and the cost of a mistake, then comprehension and the task, then effort, then visual consistency. This summary describes release 2.2.4.

  1. Establish context

    Read the brief and the product you already have. Name the audience, how often the task happens, what a mistake costs, and the device.

    Keep what you know separate from what you assume. Do not invent rules or capabilities the product lacks.

  2. Choose the visual system

    Keep a system the project already has. When it has none, select from the platform.

    For other web work, the fallback is Material 3. Borrow an interaction pattern when it solves the task. Do not copy another organization's branding.

    GOV.UK branding is for government services only.

  3. Map objects before layout

    When relationships would change the navigation, the routes, or the structure of the screen, map the objects people recognize, how they relate, and what someone can do with them.

    Skip the map when the change does not depend on those relationships, such as a copy edit or a restyle that leaves the structure alone.

    The map is a short working note. It is not a claim that the full ORCA method was completed.

  4. Write a decision record

    For a choice that would be costly to undo, record task frequency, familiarity, the cost of a mistake, the device, the pattern you chose, and why. Judge the effort to read, remember, enter, navigate, and recover.

    When the project keeps design records, save them with the work. See the design record for this page.

  5. Structure each view

    For each important view, state its purpose, the information required to decide, the actions, and the states that apply, including loading, empty, and error where they exist.

    Keep essential information visible. Adapt the layout to the device without dropping a capability the task needs.

  6. Deliver and validate

    Deliver the screen or the spec, the decisions, and a validation status.

    Label the evidence as proposed, heuristic review, automated check, manual test, or user research. Say what you did not test.

How this differs from WebHIG

Design Decision Method decides how this particular experience should work. WebHIG defines applicable interface quality requirements.

The two stay separate. This project does not copy WebHIG requirements into a second standard.

Role

Design Decision Method
Decides how this particular experience should work.
WebHIG
Defines applicable interface quality requirements.

Coverage

Design Decision Method
Chooses information hierarchy, layouts and flows.
WebHIG
Governs accessibility, consistency, responsiveness, performance and motion.

Record and checks

Design Decision Method
Records why a choice fits the audience and task.
WebHIG
Provides requirements and checks for its implementation.

When a project has no interface guidelines, the method uses the Web Content Accessibility Guidelines (WCAG) 2.2 level AA for web, or the relevant native guidance, and records any other requirements that were not specified.

Examples

These are illustrations of how the procedure applies. They are not case studies, and they do not report measured results.

  • Settings that change shape on every prompt

    Situation. You are the only developer. You ask an agent for an account settings screen. The first result is a grid of cards. You say it is too much. The next result is a different grid, with toggles you did not ask for.

    What the method asks. Name who changes settings, which ones they change often, and which mistakes are costly, such as deleting an account or changing billing.

    Map the objects people recognize, such as the account, a preference, and a connected service, before any layout.

    Record which settings stay visible and which sit behind a further step, and why.

  • A dashboard for a request that is not a dashboard

    Situation. A two-person team wants a page where a customer asks for a quote. The agent produces a sidebar, summary charts, and status tiles, because that layout is familiar from other products.

    What the method asks. The experience purpose is a short request, not operational monitoring. The object map is the quote request and the person sending it.

    Charts are out of scope, because nobody asked to monitor a workload. The record notes that offline use was not requested, so the design does not invent it.

  • Corrections that disappear on the next prompt

    Situation. An agent builds a project landing page. You rewrite the order of the page, the first sentence, and which action is primary. The next prompt regenerates the page and drops those corrections.

    What the method asks. Write the corrections down as decisions: what a visitor must understand first, what supports the choice to continue, and what can wait.

    The following prompt starts from that record. A person still checks the result. The method does not measure how many prompts that removes.

Get started

The skill follows the open Agent Skills format. Copy the whole folder, keeping the name design-decision-method, into your agent's skills directory. The name in SKILL.md must match that directory name.

Paths below were checked on 2026-10-05 against the cited docs. They can change, so confirm them again before relying on them. Copies installed in other hosts do not update when you change one copy, and no update service is configured.

  • Claude Code

    Checked on 2026-10-05 against the Claude Code skills documentation.

    In the project

    .claude/skills/

    For yourself

    ~/.claude/skills/

  • Cursor

    Checked on 2026-10-05 against the Cursor skills documentation.

    In the project

    .cursor/skills/

    or

    .agents/skills/

    For yourself

    The same two paths under your user home.

  • Gemini CLI

    Checked on 2026-10-05 against the Gemini CLI skills documentation.

    In the project

    .gemini/skills/

    or

    .agents/skills/

    For yourself

    ~/.gemini/skills/

    or

    ~/.agents/skills/

  • Codex

    Project path checked on 2026-10-05 against the Codex skills documentation. Personal directory: not verified.

    In the repository, from the working directory up to the repo root

    .agents/skills/

  • Other hosts

    Not verified. Confirm the skills directory in that host's own documentation.

  • Claude.ai

    Not verified against Claude.ai documentation in this release. The .skill export is a zip of this same folder for hosts that import a skill archive.

Agents without skill support

Paste the body of SKILL.md into your rules or instructions file, for example AGENTS.md, and keep references/ and assets/ in the repository so the paths resolve.

A short pointer in persistent memory can remind an agent to load the skill. It cannot replace the files. The README gives this wording:

Load the full Design Decision Method and its relevant references before UI/UX work. Establish audience, purpose, frequency, error consequences, and platform; apply the conditional object-map gate before layout; record consequential choices; apply project guidelines or disclose the fallback; validate purpose-specific outcomes and label tested versus untested results. Apply AI checks only to AI-enabled features.

Repository and docs

The procedure the agent reads is SKILL.md. This page is the introduction published from the docs/ folder. Release notes, install details, and integrity checks stay in the repository.