Skip to content
Back to search

omd

Design like a person, not like the mean of the training set.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/3x-haust/oh-my-design with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/3x-haust/oh-my-design'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/3x-haust--oh-my-design/badge.svg)](/listings/3x-haust--oh-my-design)

HTML

<a href="/listings/3x-haust--oh-my-design"><img src="/api/listings/3x-haust--oh-my-design/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm

npm install -g @3xhaust/oh-my-design
oh-my-design install
oh-my-design doctor

The unscoped `oh-my-design` package on npm is unrelated. `oh-my-design uninstall` reverses host installation without deleting a project's `.omd/` records.

Pi-compatible hosts

pi install npm:@3xhaust/oh-my-design

Claude Code marketplace

/plugin marketplace add 3x-haust/oh-my-design
/plugin install oh-my-design@omd

From source

git clone https://github.com/3x-haust/oh-my-design
cd oh-my-design
npm install
node bin/omd-install.ts install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 29 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "omd",
  4. "description": "Design like a person, not like the mean of the training set.",
  5. "owner": {
  6. "name": "3x-haust"
  7. },
  8. "version": "0.20.0",
  9. "plugins": [
  10. {
  11. "name": "oh-my-design",
  12. "description": "One command, ultradesign: designs a marketing page, a multi-screen product or a redesign from a one-line request, one cycle at a time. Each cycle makes the work, has a cold outside eye look at it, and stops to show you; reply \"one more\" or \"continue\".",
  13. "version": "0.20.0",
  14. "author": {
  15. "name": "3x-haust"
  16. },
  17. "source": "./",
  18. "category": "design",
  19. "homepage": "https://github.com/3x-haust/oh-my-design",
  20. "tags": [
  21. "design",
  22. "ui",
  23. "references",
  24. "typography",
  25. "motion"
  26. ]
  27. }
  28. ]
  29. }
README.md · README · 96 lines
  1. # Oh My Design
  2. [![CI](https://github.com/3x-haust/oh-my-design/actions/workflows/ci.yml/badge.svg)](https://github.com/3x-haust/oh-my-design/actions/workflows/ci.yml)
  3. [![npm](https://img.shields.io/npm/v/%403xhaust%2Foh-my-design)](https://www.npmjs.com/package/@3xhaust/oh-my-design)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  5. **AI that designs like a human.** Type one command with a one-line request. OMD makes a new marketing
  6. page, a new multi-screen product, or a redesign of an existing service, has a cold outside eye look at
  7. it, and stops to show you.
  8. [한국어](README.ko.md)
  9. ## One command
  10. | Host | Type |
  11. | --- | --- |
  12. | Pi | `/skill:omd-ultradesign <request>` |
  13. | Claude Code | `/oh-my-design:ultradesign <request>` |
  14. | Codex | `$omd-ultradesign <request>` |
  15. That is the only thing you type. Everything else runs inside it.
  16. ## How a run goes
  17. A cycle reads the project and the request, gathers references, makes its own assets, builds the key
  18. screens in the project's real code, and renders them at desktop and phone width. A fresh reviewer that
  19. sees only those captures and one real finished work names the largest sign that a senior designer did
  20. not make it.
  21. Then it stops and shows you where the result is and how to open it, the reviewer's finding, a short
  22. memo of what was learned, and what the next cycle would throw away and rebuild. Reply after the same
  23. command:
  24. - `one more` runs one more cycle and stops again.
  25. - `continue` keeps going until the reviewer finds nothing or cycle 3 is reached.
  26. - `continue without stopping: <request>` starts a request that runs that way from the beginning.
  27. Each cycle starts from a clean conversation that carries only the memo, the surviving assets and the
  28. chosen reference. On Pi the fresh session opens by itself; on Claude Code or Codex, start a new session
  29. (`/clear` or a new chat) and type the command again. Every design choice is OMD's; you decide only
  30. whether to go on.
  31. ## Install
  32. ### npm
  33. ```bash
  34. npm install -g @3xhaust/oh-my-design
  35. oh-my-design install
  36. oh-my-design doctor
  37. ```
  38. The unscoped `oh-my-design` package on npm is unrelated. `oh-my-design uninstall` reverses host
  39. installation without deleting a project's `.omd/` records.
  40. ### Pi-compatible hosts
  41. ```bash
  42. pi install npm:@3xhaust/oh-my-design
  43. ```
  44. ### Claude Code marketplace
  45. ```text
  46. /plugin marketplace add 3x-haust/oh-my-design
  47. /plugin install oh-my-design@omd
  48. ```
  49. ### From source
  50. ```bash
  51. git clone https://github.com/3x-haust/oh-my-design
  52. cd oh-my-design
  53. npm install
  54. node bin/omd-install.ts install
  55. ```
  56. ## Browser support
  57. OMD prefers its verified `browser-rs` provider on supported Darwin arm64 and Linux x64 hosts and
  58. falls back to Playwright + Chromium. If Chromium is missing, run `npx playwright install chromium`.
  59. ## Development
  60. The prompt source of truth is `src/skills/omd-ultradesign/SKILL.md` and `src/agents/`. `skills/`,
  61. `agents/` and `dist/` are generated by `npm run build`; do not edit them directly.
  62. Definition of done for a repository change:
  63. ```bash
  64. npx tsc --noEmit
  65. npm run build
  66. npm test
  67. ```
  68. Commits use conventional prefixes. Releases and version bumps happen only on explicit request.
core/design/index.ts · Bundled script · 582 lines · 1 finding marked
  1. import { existsSync, readdirSync, readFileSync } from 'node:fs';
  2. import { join } from 'node:path';
  3. import type { Violation } from '../types.ts';
  4. // ── Section schema ────────────────────────────────────────────────────────────
  5. /**
  6. * The fourteen required sections of a `.omd/design.md` contract.
  7. *
  8. * Section names are matched case-insensitively against the document's h2
  9. * headings (## Heading). The order is canonical but the validator does not
  10. * enforce order — only presence.
  11. */
  12. export const REQUIRED_SECTIONS = [
  13. 'Source of truth',
  14. 'Brand',
  15. 'Product goals',
  16. 'Personas & jobs',
  17. 'Information architecture',
  18. 'Design principles',
  19. 'Visual language',
  20. 'Components',
  21. 'Accessibility',
  22. 'Responsive behavior',
  23. 'Interaction states',
  24. 'Content voice',
  25. 'Implementation constraints',
  26. 'Open questions',
  27. ] as const;
  28. export type DesignSection = (typeof REQUIRED_SECTIONS)[number];
  29. /**
  30. * The six interaction states that must be enumerated in the "Interaction states"
  31. * section. Each state is either implemented or explicitly skipped with a reason.
  32. * The validator flags when the section exists but none of these words appear.
  33. */
  34. export const INTERACTION_STATES = [
  35. 'loading',
  36. 'empty',
  37. 'error',
  38. 'success',
  39. 'disabled',
  40. 'offline',
  41. ] as const;
  42. export type InteractionState = (typeof INTERACTION_STATES)[number];
  43. // ── Evidence scanner ──────────────────────────────────────────────────────────
  44. export interface Evidence {
  45. hasPackageJson: boolean;
  46. packageJsonReadable: boolean;
  47. framework: string | null;
  48. dependencies: string[];
  49. hasThemeTokens: boolean;
  50. tokenFilePaths: string[];
  51. surfaceCount: number;
  52. surfacePaths: string[];
  53. appEvidencePaths: string[];
  54. frameMd: string | null;
  55. decisionsMd: string | null;
  56. attributionMd: string | null;
  57. captureCount: number;
  58. captureNames: string[];
  59. hasMotionSpec: boolean;
  60. hasVoiceStudy: boolean;
  61. }
  62. /**
  63. * Scan the project at `cwd` for design evidence. Returns everything that can
  64. * be inferred without rendering a page. Unknowns stay null; the generator
  65. * converts them to open questions rather than invented values.
  66. */
  67. export function discoverEvidence(cwd: string): Evidence {
  68. const evidence: Evidence = {
  69. hasPackageJson: false,
  70. packageJsonReadable: false,
  71. framework: null,
  72. dependencies: [],
  73. hasThemeTokens: false,
  74. tokenFilePaths: [],
  75. surfaceCount: 0,
  76. surfacePaths: [],
  77. appEvidencePaths: [],
  78. frameMd: null,
  79. decisionsMd: null,
  80. attributionMd: null,
  81. captureCount: 0,
  82. captureNames: [],
  83. hasMotionSpec: false,
  84. hasVoiceStudy: false,
  85. };
  86. // package.json — framework and dependency fingerprint
  87. const pkgPath = join(cwd, 'package.json');
  88. if (existsSync(pkgPath)) {
  89. evidence.hasPackageJson = true;
  90. try {
  91. const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as {
  92. dependencies?: Record<string, string>;
  93. devDependencies?: Record<string, string>;
  94. };
  95. const all = {
  96. ...pkg.dependencies,
  97. ...pkg.devDependencies,
  98. };
  99. const names = Object.keys(all);
  100. evidence.packageJsonReadable = true;
  101. evidence.dependencies = names;
  102. if (names.some((n) => n === 'next' || n === '@next/core-web-vitals')) evidence.framework = 'next';
  103. else if (names.includes('react')) evidence.framework = 'react';
  104. else if (names.includes('vue')) evidence.framework = 'vue';
  105. else if (names.some((n) => n === 'svelte' || n === '@sveltejs/kit')) evidence.framework = 'svelte';
  106. } catch { /* corrupt package.json — skip */ }
  107. }
  108. // Fixed, high-signal application entries and build configs. These are evidence that a
  109. // repository is not blank even when it has no package.json or conventional page file yet.
  110. const appEvidenceCandidates = [
  111. 'src/main.js', 'src/main.ts', 'src/main.jsx', 'src/main.tsx',
  112. 'src/App.js', 'src/App.ts', 'src/App.jsx', 'src/App.tsx',
  113. 'src/app.js', 'src/app.ts', 'src/app.jsx', 'src/app.tsx',
  114. 'app.js', 'app.ts', 'app.jsx', 'app.tsx',
  115. 'main.js', 'main.ts', 'main.jsx', 'main.tsx',
  116. 'vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.cjs',
  117. 'webpack.config.js', 'webpack.config.ts', 'rollup.config.js', 'rollup.config.ts',
  118. 'next.config.js', 'next.config.mjs', 'next.config.ts',
  119. 'nuxt.config.js', 'nuxt.config.ts', 'svelte.config.js', 'svelte.config.ts',
  120. 'astro.config.js', 'astro.config.mjs', 'astro.config.ts',
  121. 'vue.config.js', 'angular.json', 'gatsby-config.js', 'gatsby-config.ts',
  122. ];
  123. evidence.appEvidencePaths = appEvidenceCandidates.filter((rel) => existsSync(join(cwd, rel)));
  124. // Token / theme files — CSS custom properties, tailwind config
  125. const tokenCandidates = [
  126. 'src/styles/tokens.css',
  127. 'src/styles/variables.css',
  128. 'src/tokens.css',
  129. 'tokens.css',
  130. 'styles/tokens.css',
  131. 'tailwind.config.js',
  132. 'tailwind.config.ts',
  133. 'tailwind.config.cjs',
  134. 'theme.ts',
  135. 'theme.js',
  136. 'src/theme.ts',
  137. 'src/theme.js',
  138. ];
  139. for (const rel of tokenCandidates) {
  140. const abs = join(cwd, rel);
  141. if (existsSync(abs)) {
  142. evidence.hasThemeTokens = true;
  143. evidence.tokenFilePaths.push(rel);
  144. }
  145. }
  146. // Surface discovery — count HTML/page/route files as a proxy for surface count
  147. const surfaceDirs = ['src/app', 'src/pages', 'pages', 'src/routes', 'routes'];
  148. for (const dir of surfaceDirs) {
  149. const abs = join(cwd, dir);
  150. if (!existsSync(abs)) continue;
  151. try {
  152. const files = readdirSync(abs, { recursive: true }) as string[];
  153. const pages = files.filter((f) =>
  154. f.endsWith('.tsx') || f.endsWith('.jsx') ||
  155. f.endsWith('.vue') || f.endsWith('.svelte') ||
  156. f.endsWith('.html'),
  157. );
  158. if (pages.length > 0) {
  159. evidence.surfacePaths.push(...pages.slice(0, 20).map((f) => `${dir}/${f}`));
  160. evidence.surfaceCount += pages.length;
  161. }
  162. } catch { /* unreadable — skip */ }
  163. }
  164. // Fallback: count HTML files at root and dist/
  165. if (evidence.surfaceCount === 0) {
  166. for (const dir of [cwd, join(cwd, 'dist'), join(cwd, 'public')]) {
  167. if (!existsSync(dir)) continue;
  168. try {
  169. const files = readdirSync(dir);
  170. const htmlFiles = files.filter((f) => f.endsWith('.html') || f.endsWith('.htm'));
  171. evidence.surfaceCount += htmlFiles.length;
  172. evidence.surfacePaths.push(...htmlFiles.map((f) => dir === cwd ? f : `${join(dir, f).slice(cwd.length + 1)}`));
  173. } catch { /* skip */ }
  174. }
  175. }
  176. // .omd/ artifacts
  177. const omdDir = join(cwd, '.omd');
  178. const framePath = join(omdDir, 'frame.md');
  179. if (existsSync(framePath)) evidence.frameMd = readFileSync(framePath, 'utf8');
  180. const decisionsPath = join(omdDir, 'decisions.md');
  181. if (existsSync(decisionsPath)) evidence.decisionsMd = readFileSync(decisionsPath, 'utf8');
  182. const attrPath = join(omdDir, 'attribution.md');
  183. if (existsSync(attrPath)) evidence.attributionMd = readFileSync(attrPath, 'utf8');
  184. const motionSpecPath = join(omdDir, 'motion-spec.md');
  185. if (existsSync(motionSpecPath)) evidence.hasMotionSpec = true;
  186. const voiceStudyPath = join(omdDir, 'voice-study.md');
  187. if (existsSync(voiceStudyPath)) evidence.hasVoiceStudy = true;
  188. const refsDir = join(omdDir, 'refs');
  189. if (existsSync(refsDir)) {
  190. try {
  191. const jsonFiles = readdirSync(refsDir).filter((f) => f.endsWith('.json'));
  192. evidence.captureCount = jsonFiles.length;
  193. evidence.captureNames = jsonFiles.map((f) => f.slice(0, -5));
  194. } catch { /* skip */ }
  195. }
  196. return evidence;
  197. }
  198. // ── Design.md generator ───────────────────────────────────────────────────────
  199. /**
  200. * Generate the initial `.omd/design.md` content from discovered evidence.
  201. *
  202. * The file is an English-language design contract. Every field that cannot be
  203. * inferred from evidence becomes an explicit open question rather than an
  204. * invented value. A bare project with no evidence produces a skeleton that the
  205. * designer fills in; a project with frame.md and token files produces a
  206. * partially-populated contract.
  207. */
  208. export function generateDesignMd(evidence: Evidence): string {
  209. const now = new Date().toISOString().slice(0, 10);
  210. const surfaceSummary = evidence.surfaceCount > 0
  211. ? `${evidence.surfaceCount} surface${evidence.surfaceCount === 1 ? '' : 's'} detected: ${evidence.surfacePaths.slice(0, 5).join(', ')}${evidence.surfaceCount > 5 ? ` (+${evidence.surfaceCount - 5} more)` : ''}`
  212. : 'No existing surface detected';
  213. const frameSummary = evidence.frameMd
  214. ? `Derived from .omd/frame.md:\n ${evidence.frameMd.split('\n').slice(0, 3).join('\n ')}`
  215. : 'Open question — run `omd frame set` to establish the problem statement';
  216. const frameworkNote = evidence.framework
  217. ? `${evidence.framework} (detected via package.json)`
  218. : evidence.hasPackageJson
  219. ? `Unrecognised package/toolchain (${evidence.packageJsonReadable ? 'package.json inspected' : 'package.json unreadable'})`
  220. : evidence.surfaceCount > 0
  221. ? 'Existing surface without package.json'
  222. : evidence.appEvidencePaths.length > 0
  223. ? `Existing application/toolchain evidence: ${evidence.appEvidencePaths.join(', ')}`
  224. : 'No existing repository stack detected';
  225. // The generator has repository evidence, not the user's brief. It therefore records
  226. // the build-time precedence instead of pretending to know whether the brief overrides it.
  227. const stackPolicy = evidence.surfaceCount > 0
  228. ? 'Preserve the existing surface and repository toolchain; inspect before changing it and do not replace it with a new scaffold.'
  229. : evidence.framework
  230. ? `Preserve the detected ${evidence.framework} repository stack/toolchain.`
  231. : evidence.hasPackageJson
  232. ? 'Inspect and preserve the existing unrecognised package/toolchain; do not replace it with React or another scaffold.'
  233. : evidence.appEvidencePaths.length > 0
  234. ? 'Inspect and preserve the existing application/toolchain evidence; do not replace it with a new scaffold.'
  235. : 'React + Vite + TypeScript default unless explicit brief override. Plain HTML requires an explicit user request.';
  236. const dependencyPolicy = evidence.surfaceCount > 0 || evidence.hasPackageJson || evidence.appEvidencePaths.length > 0
  237. ? 'Do not add unnecessary dependencies to this existing project.'
  238. : 'Greenfield scaffold dependencies for React + Vite + TypeScript are allowed.';
  239. const tokenNote = evidence.hasThemeTokens
  240. ? `Token files found: ${evidence.tokenFilePaths.join(', ')}`
  241. : 'No token files found — define `:root` CSS custom properties or a theme config';
  242. const referenceNote = evidence.captureCount > 0
  243. ? `${evidence.captureCount} reference capture${evidence.captureCount === 1 ? '' : 's'}: ${evidence.captureNames.slice(0, 5).join(', ')}${evidence.captureCount > 5 ? ` (+${evidence.captureCount - 5} more)` : ''}`
  244. : 'No references captured yet — run `omd ref add` to populate the board';
  245. return `# Design contract
  246. > This file is the persistent design contract for this project. It is the upstream
  247. > authority for every surface decision. Established by \`omd design\`, maintained by
  248. > the designer. Everything under \`.omd/\` is English; this contract is no exception.
  249. ---
  250. ## Source of truth
  251. - **Status**: draft
  252. - **Date**: ${now}
  253. - **Surfaces**: ${surfaceSummary}
  254. - **Repository app/toolchain evidence**: ${evidence.appEvidencePaths.length > 0 ? evidence.appEvidencePaths.join(', ') : 'none detected'}
  255. - **Evidence**: ${referenceNote}
  256. - **Framework**: ${frameworkNote}
  257. - **Tokens**: ${tokenNote}
  258. ---
  259. ## Brand
  260. - **Personality**: <!-- Open question: what three adjectives describe this brand's character? -->
  261. - **Trust signals**: <!-- Open question: what makes users trust this product? domain expertise, testimonials, price transparency, certifications? -->
  262. - **Avoid**: <!-- Open question: what aesthetics, tones, or references does this brand explicitly reject? -->
  263. ---
  264. ## Product goals
  265. ${frameSummary}
  266. <!-- Open question: what are the top two or three measurable outcomes this product must achieve? -->
  267. ---
  268. ## Personas & jobs
  269. <!-- Open question: who uses this product and what job are they hiring it to do?
    • Note: Quoted as data in code: Gives the agent orders in an HTML comment, which the rendered page hides from a reader
    • Line 313 on GitHub
  270. Format: Persona name — one sentence on who they are and what they need to accomplish. -->
  271. ---
  272. ## Information architecture
  273. <!-- List the surfaces, their hierarchy, and the primary user path through them.
  274. Example:
  275. - / (home) — first impression, conversion
  276. - /pricing — decision
  277. - /docs — activation
  278. Primary path: home → pricing → sign up
  279. UX decision constraints (see theory/ux.md):
  280. - Name the primary task the user arrives with on each surface.
  281. - Name the most frequent action per surface (defaults are set for this case).
  282. - Name the costliest error per surface and confirm a recovery path exists.
  283. - Every state the user can reach must have an exit (no dead ends). -->
  284. ---
  285. ## Design principles
  286. <!-- Two to four product-specific principles that resolve conflicts when two valid choices both work.
  287. Example: "Clarity beats cleverness — when a UI pattern is clever but unfamiliar, use the familiar one." -->
  288. ---
  289. ## Visual language
  290. ### Color
  291. <!-- Token names and roles. Fill from .omd/attribution.md if present. -->
  292. ### Typography
  293. <!-- Type scale, font families, weight ladder. -->
  294. ### Spacing
  295. <!-- Spacing ladder. -->
  296. ### Radius
  297. <!-- Corner radius ladder. -->
  298. ### Motion
  299. ${evidence.hasMotionSpec
  300. ? '<!-- Refer to .omd/motion-spec.md for scene-level detail. Summarise the overall motion vocabulary here. -->'
  301. : '<!-- Open question: duration range, easing vocabulary, and whether motion is decorative or functional. -->'}
  302. ---
  303. ## Components
  304. ### Reused (already built)
  305. <!-- List components already in the codebase with their location. -->
  306. ### New (to be built)
  307. <!-- List components that do not yet exist and must be built. -->
  308. ### Variants
  309. <!-- Which components need size/color/state variants? List them. -->
  310. ### States
  311. <!-- Which components carry interaction states? Cross-reference Interaction states section below. -->
  312. ---
  313. ## Accessibility
  314. - **Target**: WCAG 2.2 AA minimum
  315. - **Language**: <!-- primary language, e.g. "ko" for Korean. Determines word-break rules. -->
  316. - **Focus management**: <!-- any non-standard focus routing (modals, skip-nav, single-page navigation)? -->
  317. ---
  318. ## Responsive behavior
  319. - **Breakpoints**: 375px (base) / 768px / 1280px
  320. - **Mobile-first**: yes — base styles target 375px, larger viewports layer on top
  321. - **Exceptions**: <!-- any surfaces that are desktop-only or have non-standard breakpoints? -->
  322. ---
  323. ## Interaction states
  324. Every interactive surface must account for all applicable states. Each state is either
  325. implemented or explicitly skipped with a reason recorded in \`omd decision\`.
  326. ### Loading
  327. <!-- How does the UI signal that data is in flight? Skeleton, spinner, shimmer, or disabled state?
  328. Which surfaces show loading: forms (after submit), data lists, async navigation? -->
  329. ### Empty
  330. <!-- What does a data list, feed, or result set show when there is nothing to display?
  331. An empty container is a design defect. Every list needs an empty state. -->
  332. ### Error
  333. <!-- How are error conditions surfaced? Form validation errors (field-level + summary),
  334. network failures, permission errors. Minimum: role=alert on error messages,
  335. aria-invalid on failed fields, visible error copy that states what to do next. -->
  336. ### Success
  337. <!-- How is a completed action confirmed? Inline confirmation, toast, page transition,
  338. or a dedicated success screen? Duration and dismissal behaviour. -->
  339. ### Disabled
  340. <!-- Disabled elements must still communicate why they are disabled. A greyed-out button
  341. with no tooltip is an accessibility failure. Either remove the element when the
  342. action is unavailable, or pair the disabled state with explanatory copy. -->
  343. ### Offline
  344. <!-- Does this product have any offline capability or offline-detection UI?
  345. If not, document that it is an explicit non-requirement. -->
  346. ---
  347. ## Content voice
  348. ${evidence.hasVoiceStudy
  349. ? '<!-- Derived from .omd/voice-study.md. Summarise the register, vocabulary temperature, and sentence rhythm rules here. -->'
  350. : '<!-- Open question: what register does this product use? Formal/informal, warm/authoritative, Korean 해요체/합니다체. Cite a voice study capture from the reference board. -->'}
  351. ---
  352. ## Implementation constraints
  353. - **Stack precedence**: explicit user request > existing repository stack/toolchain (including existing vanilla HTML) > React + Vite + TypeScript only for a truly blank greenfield
  354. - **Build-time stack policy**: ${stackPolicy}
  355. - **Dependencies**: ${dependencyPolicy}
  356. - **Browser targets**: last 2 major versions of Chrome, Firefox, Safari, Edge
  357. - **Performance**: <!-- any specific performance budget? LCP target, bundle size limit? -->
  358. - **Frameworks/libraries already in use**: ${frameworkNote}
  359. - **Additional constraints**: <!-- any deploy environment, CMS, or accessibility certification constraints? -->
  360. ---
  361. ## Open questions
  362. <!-- Collect unresolved decisions here. Each question should name who can answer it
  363. and what the consequence of the default assumption is.
  364. Template:
  365. - Q: [question]
  366. Default assumption: [what will be implemented if unanswered]
  367. Consequence if wrong: [what breaks or must be rebuilt]
  368. Owner: [designer / product / engineering]
  369. -->
  370. `;
  371. }
  372. // ── Parser ────────────────────────────────────────────────────────────────────
  373. /**
  374. * Parse the h2 section headings present in a design.md document.
  375. * Returns a map from normalised heading text to the section body content.
  376. *
  377. * Normalisation: trimmed, lowercased. Matching against REQUIRED_SECTIONS
  378. * is done case-insensitively at the call site.
  379. */
  380. export function parseDesignSections(md: string): Map<string, string> {
  381. const map = new Map<string, string>();
  382. // Split on h2 headings; slice(1) drops the preamble before the first ##.
  383. const chunks = md.split(/^##\s+/m).slice(1);
  384. for (const chunk of chunks) {
  385. const nl = chunk.indexOf('\n');
  386. const heading = (nl === -1 ? chunk : chunk.slice(0, nl)).trim();
  387. const body = nl === -1 ? '' : chunk.slice(nl + 1);
  388. if (heading) map.set(heading.toLowerCase(), body);
  389. }
  390. return map;
  391. }
  392. /**
  393. * Find the canonical REQUIRED_SECTIONS entry that matches a parsed heading,
  394. * or null when no match is found.
  395. */
  396. function matchSection(heading: string): DesignSection | null {
  397. const lower = heading.toLowerCase();
  398. for (const s of REQUIRED_SECTIONS) {
  399. if (s.toLowerCase() === lower) return s;
  400. }
  401. return null;
  402. }
  403. // ── Validator ─────────────────────────────────────────────────────────────────
  404. /**
  405. * Validate a design.md document against the required section schema.
  406. *
  407. * Two violation codes:
  408. *
  409. * DESIGN-INCOMPLETE A required section is missing entirely from the document.
  410. *
  411. * DESIGN-INCOMPLETE The "Interaction states" section exists but does not
  412. * enumerate any of the six required states (loading/empty/
  413. * error/success/disabled/offline). A section that exists but
  414. * leaves all states blank is worse than no section at all —
  415. * it gives a false impression of coverage.
  416. *
  417. * Only called when `.omd/design.md` exists (the caller guards that). A bare project
  418. * without design.md is not nagged.
  419. */
  420. export function validateDesignMd(md: string): Violation[] {
  421. const violations: Violation[] = [];
  422. const sections = parseDesignSections(md);
  423. // Collect which required sections are present via case-insensitive match.
  424. const missing: DesignSection[] = [];
  425. for (const required of REQUIRED_SECTIONS) {
  426. const found = [...sections.keys()].some((k) => matchSection(k) === required);
  427. if (!found) missing.push(required);
  428. }
  429. for (const section of missing) {
  430. violations.push({
  431. id: 'DESIGN-INCOMPLETE',
  432. severity: 'warn',
  433. layer: 1,
  434. category: 'system',
  435. nodeId: 'page',
  436. path: 'design',
  437. value: section,
  438. message: `design.md is missing the "${section}" section. Run \`omd design\` to refresh the contract, then fill in the open question.`,
  439. });
  440. }
  441. // Interaction states section exists but enumerates no states.
  442. const interactionBody = [...sections.entries()]
  443. .find(([k]) => matchSection(k) === 'Interaction states')?.[1] ?? null;
  444. if (interactionBody !== null) {
  445. // Only explicit state declarations count; a passing prose mention is not coverage.
  446. const declared = new Set([...interactionBody.matchAll(/^(?:###\s+|\s*[-*]\s*)(loading|empty|error|success|disabled|offline)(?:\s*:|\s*$)/gim)].map(match => match[1]!.toLowerCase()));
  447. const enumerated = INTERACTION_STATES.filter((s) => declared.has(s));
  448. if (enumerated.length === 0) {
  449. violations.push({
  450. id: 'DESIGN-INCOMPLETE',
  451. severity: 'warn',
  452. layer: 1,
  453. category: 'system',
  454. nodeId: 'page',
  455. path: 'design',
  456. value: 'Interaction states: (blank)',
  457. message:
  458. 'design.md has an "Interaction states" section but it does not enumerate any states '
  459. + '(loading/empty/error/success/disabled/offline). A section that exists but leaves '
  460. + 'all states blank gives false coverage assurance. Fill in each state or skip it '
  461. + 'with a written reason.',
  462. });
  463. } else {
  464. // Partial coverage: states present but some missing.
  465. const missing2 = INTERACTION_STATES.filter((s) => !declared.has(s));
  466. for (const state of missing2) {
  467. violations.push({
  468. id: 'DESIGN-INCOMPLETE',
  469. severity: 'warn',
  470. layer: 1,
  471. category: 'system',
  472. nodeId: 'page',
  473. path: 'design',
  474. value: `Interaction states: missing ${state}`,
  475. message:
  476. `design.md "Interaction states" section does not mention "${state}". `
  477. + 'Either implement this state and document it, or explicitly skip it with a reason in `omd decision`.',
  478. });
  479. }
  480. }
  481. }
  482. return violations;
  483. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.