# Design Decision Method ## What is it? Design Decision Method is a reusable workflow for people and AI agents to decide what information a screen needs, how to organize it, and which interactions and visual direction fit the project. It draws on established guidance. It does not create another UI library or visual standard. ## What does it solve? It addresses repeated UI guesswork: starting from generic layouts, overlooking essential information, adding unnecessary complexity, and revisiting the same decisions across projects. It makes consequential choices explicit before building. ## Why do we need it? For our work, it carries the same design philosophy across products and agents: simple to understand, informative enough to decide, and efficient to use. It reduces the need to explain that philosophy from scratch each time. Whether it actually saves time still needs measurement. It is useful as a shared procedure, and it is not mandatory for every small edit. The opening points above are also published as a page from the `docs/` folder: https://frozonfreak.github.io/DesignDecesionMethod/ The agent procedure routes UI work across OOUX, GOV.UK, Carbon, Material 3, platform guidelines, and a project's own rules. When relationships shape structure, it requires a short object map and decision record before layout, and it ends with an honest validation status. It does not rank those sources, copy their branding, or claim research or compliance it has not done. This README is for people. The agent reads `SKILL.md`. Current release: 2.4.1. ## Contents ``` design-decision-method/ ├── SKILL.md core procedure ├── references/ │ ├── modern-design.md purpose-based presentation, specialist extension │ ├── audience-and-page-patterns.md optional marketing questions and evidence prompts │ ├── routing.md which guidance for which problem │ ├── visual-systems.md currency snapshot and adoption checks │ ├── accessibility.md WCAG 2.2 AA baseline and checks │ ├── ai-interfaces.md only for AI-enabled features │ ├── acceptance-and-validation.md criteria format and evidence levels │ └── sources.md lookup routes and verification ├── modules/landing-pages/ conditionally loaded ULPG 0.4.0 (see GUIDE.md) ├── evals/landing-pages/ five combined scenarios and protocol.md ├── assets/design-record-template.md object map and decision record ├── evals/evals.json test prompts ├── agents/openai.yaml optional metadata for hosts that read it ├── release-manifest.json file hashes ├── CHANGELOG.md ├── LICENSE MIT License └── README.md ``` ## Integrated landing-page module DDM 2.4.0 includes ULPG v0.4.0 as a first-class, conditionally loaded module, integration revision 1. Copy the entire package, including `modules/`, when installing; agents without skill support must keep that folder alongside the core references. Unrelated work does not load it. Small edits reuse established decisions and assess only affected requirements. `modules/landing-pages/GUIDE.md` routes to entry-and-navigation.md, content-and-trust.md, interaction-and-demonstrations.md, technical-quality.md and validation.md. All twenty ULPG sections retain their wording and levels. `traceability.md` and `traceability.json` map section/requirement retention; `PROVENANCE.md` records source and boundaries. `references.md`, LICENSE, templates (page-brief.md, review.md, decision-record.md, performance-budget.md and third-party-inventory.md), and examples (editorial-review.md and entry-pattern-regression.md) travel with the module. The module remains internally versioned separately from DDM; Web HIG is independent. The original seventeen cases remain unchanged in evals/evals.json. `evals/landing-pages/cases.json` supplies five same-brief fixtures; `evals/landing-pages/protocol.md` defines the three preservation suites. Source retention and packaging can be checked automatically. Paired agent behavior and implemented-page outcomes remain unverified; this integration does not retire the ULPG repository. The root DDM license remains unchanged, and the module retains ULPG contributors' separate MIT notice. ## Install 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. Cursor's project and user directories were checked again on 2026-11-06 and still match. The other rows were not re-opened. Paths can change, so confirm them again before relying on them. | Agent | Where to put `design-decision-method/` | Verification | |---|---|---| | Claude Code | `.claude/skills/` in the project, or `~/.claude/skills/` for yourself | Checked [Claude Code skills](https://code.claude.com/docs/en/skills.md) | | Cursor | `.cursor/skills/` or `.agents/skills/` in the project, or the same two paths under your user home | Checked [Cursor skills](https://cursor.com/docs/skills) | | Gemini CLI | `.gemini/skills/` or `.agents/skills/` in the project, or `~/.gemini/skills/` or `~/.agents/skills/` | Checked [Gemini CLI skills](https://geminicli.com/docs/cli/skills.md) | | Codex | `.agents/skills/` in the repository, from the working directory up to the repo root | Project path checked on [Codex skills](https://developers.openai.com/codex/skills). Personal directory: not verified | | Others | Confirm in that host's own docs | not verified | **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/`, `modules/` and `assets/` in the repository so the paths resolve. A short pointer in persistent memory can remind an agent to load the skill, but it cannot replace the files: > 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. ## WebHIG Design Decision Method (DDM) helps you decide what to design and why. You can use it on its own. For web projects, [WebHIG](https://frozonfreak.github.io/webhig/) gives detailed requirements for how the resulting interface should behave. This repository does not copy those requirements into a second standard. DDM can work with other applicable interface guidelines. When a project has no interface guidelines, the method uses WCAG 2.2 AA for web, or the relevant native guidance, and records any other requirements that were not specified. | | What it helps you do | Example | |---|---|---| | WebHIG | Build interfaces that behave clearly, consistently and accessibly | Make errors understandable and preserve entered information when saving fails | | Design Decision Method (DDM) | Choose an interface that fits the people and task | Decide whether a task needs one form or a step-by-step flow | ## Release and integrity `release-manifest.json` lists a SHA-256 for every file except itself, plus a canonical checksum over the sorted relative paths and exact file bytes (path, NUL byte, bytes, NUL byte). Matching hashes show that two copies have identical content. They do not show authenticity, freshness, or design quality. Different zip exports can contain the same files and still differ as archives. - Copies installed in other hosts do not update when you change one copy, and no update service is configured. - When delegating to another agent, give it the same release, the project brief, and the relevant evidence. - Any content change needs a new version in `SKILL.md` metadata, the manifest, and the changelog. - There is no automated freshness service. Re-check a source when you rely on it, and record what you actually opened. ## Check it The Agent Skills specification documents this format check, for a folder named `design-decision-method`. The `skills-ref` tool was unavailable for 2.3.0; no portable-format validator result is claimed for 2.4.0. The installed skill-creator quick validator was attempted and rejected the pre-existing `compatibility` field; it is narrower than the portable format. That result is not treated as a reason to remove existing portable metadata. The repository's release and integrity checks passed, and both archives were generated; these are package checks, not behavioural evidence. ``` skills-ref validate ./design-decision-method ``` `evals/evals.json` holds seventeen prompts: the original ten and seven communication/landing-page cases. Give the performing agent only the `prompt` field. Do not include `expected_output` or `expectations`; those are grader-only. Run each prompt in a separate context. Case 10, "Design a logo for my bakery.", is an automatic-trigger test: do not mention or force-load this method in that prompt. Keep normal skill discovery available to test whether the method stays unused. This does not measure usability or time saved. The original ten cases have not been run for 2.2.5, all seventeen remain unrun for 2.3.0, and paired comparisons against 2.4.0 remain unrun. Release 2.4.1 is a source-record refresh and was not part of that comparison. No behavioural comparison, non-regression claim or user-outcome result is reported. A package check cannot show whether an object map happened before layout, or whether a task is usable. Report proposed, heuristic, automated, manual, and user-research evidence separately. For the planned baseline/candidate comparison: 1. Preserve a 2.2.5 package and run the original ten cases in independent contexts before evaluating the candidate. Save the actual outputs and grade against the original expectations. 2. Run all seventeen cases against both 2.2.5 and 2.3.0, reusing baseline outputs only when model, settings, prompt, context, tools and scoring conditions match. Give each performer a fresh context, the same raw brief and only the skill release under test; keep grader expectations hidden. For case 10, test automatic discovery rather than explicit invocation. 3. Grade process correctness, information sufficiency, WebHIG independence, system preservation, actionable reasoning, unnecessary process and evidence honesty. Record model/settings, available tools, loaded reference scope, output token counts (or label a length proxy), and verbosity overhead. Distinguish a with-method/without-method study from this version comparison. 4. Investigate every original-case regression individually; do not average it away. New cases must add useful decisions without extra irrelevant maps, forced CTAs, brand changes or fabricated claims. Save per-case output, grading rationale and tested/untested status in the ignored output directory configured in `.gitignore` or outside the package. Behavioural observations do not establish end-user usability or conversion. From the repository root, after Python 3 is available: ``` python scripts/validate_release.py python scripts/test_integrity.py python scripts/package_release.py ``` `validate_release.py` checks YAML and JSON structure, version agreement, evaluation ids and fields, nested local references and Markdown links, module source retention, manifest coverage, file hashes, and the canonical checksum. `test_integrity.py` confirms that altered/missing files, weakened source requirements, broken nested links and rewritten baseline cases are rejected, and validates an extracted export. `package_release.py` writes `dist/design-decision-method.zip` and `dist/design-decision-method.skill`, each with the enclosing `design-decision-method/` folder. The export contains the skill files listed above. Repository scripts, CI, and ignore rules stay in git and are not part of the skill package. On Windows, `py -3` works in place of `python`. ## Keeping it current Design systems change. Re-check the snapshot in `references/visual-systems.md` against the exact source URL, and record the publication date, last-update date, access date, available version, reviewed scope, and verification status. Use "not stated" or "not verified" when that is the honest value. Update `metadata.updated` and regenerate the manifest. Do not treat a landing-page check as pattern verification. ## License This project is licensed under the MIT License. See [LICENSE](LICENSE).