@3xhaust/oh-my-design 0.16.1

package/src/skills/omd-figma/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: omd-figma
+description: >-
+  Implement a Figma design end to end: pull the file, synthesize the design system,
+  build each frame pixel-faithfully with an iterative diff loop, match responsive
+  pairs, and ship with a fidelity report. Use when a figma.com link is present in
+  the brief — the design decisions were already made in Figma; the job here is
+  faithful implementation and systematization, not concept invention.
+  Triggers: 피그마, figma link, 피그마 그대로 구현, any figma.com URL in the brief.
+---
+
+# omd-figma
+
+When Figma exists, the design is already decided. The frame/concept/reference steps
+of the design loop are not needed — someone made those choices, and they are visible
+in the file. The job here is different: read what was designed, build it faithfully,
+systematize it so the implementation can be maintained, and tell the user honestly
+how close the build got.
+
+The slop linter still runs. If the *original Figma design* fires slop rules, report
+that to the user as information — never silently "fix" their design. The user hired
+a faithful implementation, not a corrected one.
+
+---
+
+## Before anything: check the environment and the token
+
+```bash
+omd doctor
+```
+
+Run `omd doctor` first, quietly. If any check fails, surface the failure in one
+sentence and stop. A missing Playwright installation or an unwritable `.omd/` will
+break every subsequent step, and discovering that mid-loop is wasteful.
+
+`omd figma pull` requires a Figma personal access token. This is the **one allowed
+user interaction** in the skill. Check for it before pulling:
+
+```bash
+echo $FIGMA_TOKEN
+```
+
+If `FIGMA_TOKEN` is absent, tell the user exactly how to create one and where to set
+it, then stop:
+
+> To use `omd-figma`, you need a Figma personal access token.
+>
+> 1. Open Figma → **Account settings** (your avatar, top-left) → **Security** tab.
+> 2. Under **Personal access tokens**, click **Generate new token**.
+>    Scopes: **File content** (read) is sufficient.
+> 3. Copy the token and set it in your shell:
+>    ```bash
+>    export FIGMA_TOKEN=figd_...
+>    ```
+>    To persist it, add that line to `~/.zshrc` or `~/.bashrc`.
+> 4. Then re-run the skill.
+
+Do not attempt to proceed without the token. Do not invent a workaround.
+
+---
+
+## 1. PULL — read the Figma file
+
+```bash
+omd figma pull <figma-url>
+```
+
+This writes `.omd/figma/snapshot.json` — the normalized page → frame → node tree —
+and prints a page/frame inventory so the implementer can see what they are building.
+The snapshot includes a `responsive` section: frames grouped into breakpoint sets by
+the name-suffix and structure-similarity heuristics. Read this section before
+building. It is the answer to "which frames go together."
+
+The pull also computes responsive pairs (F4). Read the `responsive.breakpointSets`
+section to understand which frames are desktop/tablet/mobile variants of the same
+screen. Unpaired frames are in `responsive.unmatched` — they will fall back to the
+dual-viewport rule (build once, diff at the frame's own width; record that the
+pairing was a fallback).
+
+---
+
+## 2. SYSTEM — design system before any frame
+
+```bash
+omd figma system
+```
+
+This reads the snapshot and writes two artifacts:
+- `.omd/figma/design-system.md` — color palette, type scale, spacing, radii,
+  shadows, and the component inventory as a human-readable table.
+- A `:root` CSS file with all tokens as custom properties, ready to paste into
+  the build's stylesheet.
+
+**Build the design system before any frame.** Components with variants become React
+components (when the project is React) or standalone CSS classes with modifier
+variants. Build each component set once; every frame that uses it is an instance,
+not a copy. A component that appears in three frames is implemented three times
+only if you did not read the inventory.
+
+Record the component decisions:
+
+```bash
+omd decision "Button component: 3 variants (Size=sm/md, State=default/hover)" \
+  --why "component set from snapshot; variant props map directly to CSS modifiers"
+```
+
+---
+
+## 3. BUILD LOOP — per-frame, pixel-faithful, max 4 iterations
+
+For each frame in the inventory (name-matched responsive pairs count as one build
+target with multiple viewports):
+
+**① Build the frame** — using the design system tokens from step 2, not hardcoded
+values. Every color is a `var(--color-*)`, every spacing is a `var(--spacing-*)`,
+every radius is a `var(--radius-*)`.
+
+**② Diff**
+
+```bash
+omd figma diff <frame-id> <rendered-page> --json
+```
+
+Read the `cells` array. Find the worst cells (highest `mismatch`). The cell
+coordinates are in the reference image's pixel space — they tell you *where* the
+divergence is, not just how much.
+
+**③ Fix** — address the worst cells. Typical causes: wrong component size, wrong
+spacing token, missing border, wrong font weight. Fix the specific region the diff
+named; do not guess.
+
+**④ Re-diff** — repeat until `score ≥ 0.97` or the iteration ceiling is reached.
+
+**Ceiling: 4 iterations per frame.** After 4, record the final score and move on.
+A frame that reaches the ceiling with score < 0.97 is not a failure of the loop —
+it is honest data. The fidelity report will show it.
+
+Record each frame's final score:
+
+```bash
+omd decision "Hero frame: final score 0.983 (3 iterations)" \
+  --why "font rendering divergence on large display text; within antialiasing tolerance"
+```
+
+---
+
+## 4. RESPONSIVE — paired frames, honest fallbacks
+
+For each breakpoint set in `responsive.breakpointSets`:
+- Build each variant at its own viewport width.
+- Diff each variant against its own Figma export (the diff tool renders at the
+  frame's declared width).
+- Report scores per variant in the fidelity table.
+
+For frames in `responsive.unmatched` (no Figma-side viewport partner):
+- Apply the dual-viewport rule: build once, render at 1280px and 375px, check both,
+  record that the responsive pairing was a **fallback** (no Figma reference for the
+  missing viewport).
+- The fallback is not a gap in the implementation — it is an honest statement that
+  the design did not specify a mobile layout, and the build interpolated one.
+
+```bash
+omd decision "Contact page: no mobile variant in Figma — dual-viewport fallback applied" \
+  --why "responsive.unmatched; mobile layout interpolated from desktop, not diffed"
+```
+
+---
+
+## 5. SLOP CHECK — the original design, honestly reported
+
+After all frames are built, run the slop linter on each page:
+
+```bash
+omd check <page> --category slop --json
+```
+
+If the slop linter fires on findings that trace back to the original Figma design
+(the indigo gradient that was in Figma, the three identical feature cards that were
+in the design), **report them to the user as information, not corrections**:
+
+> The original Figma design has these slop findings: `SLOP-GRADIENT` (hero
+> background), `SLOP-TRIPLE-CARD` (features section). The build implements the
+> design as specified. If you want these addressed, update the Figma file and
+> re-pull, or override them with a written reason.
+
+Never silently "fix" the design. The user's Figma file is the source of truth.
+
+If findings arise from the *implementation* (a gradient the build introduced that
+was not in the Figma file), fix them — those are build errors, not design choices.
+
+---
+
+## 6. SHIP — fidelity report, attribution, deliver
+
+Run the full check suite:
+
+```bash
+omd check <page> --json --viewport 1280x800
+omd check <page> --json --viewport 375x812
+```
+
+Then deliver the working implementation plus a fidelity report table. The table is
+not a decoration — it is the honest record of how close the build got to the design.
+
+**Fidelity report format:**
+
+| Frame | Viewport | Score | Iterations | Notes |
+|---|---|---|---|---|
+| Hero | 1440px (desktop) | 0.983 | 3 | Font AA delta on display heading |
+| Hero | 375px (mobile) | 0.978 | 2 | — |
+| Features | 1440px | 0.997 | 1 | — |
+| Contact | 1440px | 0.965 | 4 | Ceiling reached; map embed diff |
+| Contact | 375px | — | — | Fallback: no Figma mobile frame |
+
+Include the attribution map. The frame IDs are the sources. `.omd/attribution.md`
+should record which Figma frame each token group was extracted from:
+
+```
+| Decision              | Source                     | Reason                           |
+|---|---|---|
+| --color-bg: #ffffff   | snapshot frame:1:2 (Hero)  | dominant fill, luminance=1       |
+| --type-scale-1: 48px  | snapshot frame:1:2 (Hero)  | display heading fontSize         |
+| Button component      | component set "Button"     | variant matrix from system step  |
+```
+
+Everything lands in `.omd/figma/` and `.omd/attribution.md`, committed with the repo.
+
+---
+
+## Relationship to omd-ultradesign
+
+When a Figma file is in the brief, the design decisions — concept, colour, type,
+layout — were made in Figma. The ultradesign loop's frame/concept/reference steps
+(steps 1–3) are not needed and should not run. Hand off here.
+
+The discipline of the ultradesign loop that *does* carry over:
+- The slop linter runs. If the original design fires findings, report them honestly.
+- Attribution is tracked. Frame IDs are the source entries.
+- Motion: if the Figma file includes motion prototyping, read it and record a
+  `.omd/motion-spec.md`; if not, the motion decision falls to the implementer and
+  must be recorded.
+
+---
+
+## Constraints
+
+- **Never ask the user for the token twice.** If it was set, `$FIGMA_TOKEN` is there.
+- **Never fix the original design silently.** Report slop findings that trace back
+  to Figma; let the user decide.
+- **Never hardcode a hex value from the snapshot.** Use `var(--color-*)` from the
+  design system output.
+- **Never copy a component implementation across frames.** Build it once, use it
+  everywhere.
+- **Never stop the loop before running the diff.** An unverified build is not a
+  faithful implementation — it is a guess.
+- **Never claim a score you did not measure.** Read the diff output; do not estimate.

package/src/skills/omd-humanize/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: omd-humanize
+description: >-
+  Rewrite chat, assistant replies, UI copy, pages, essays, and documentation into natural,
+  situation-aware discourse without changing facts. Repairs mechanical prose locally or
+  reconstructs a misshapen message from verified facts and its voice contract.
+  Triggers: humanize, 사람같이, 사람처럼 써, AI티 빼줘, 자연스럽게 바꿔, 글 다듬어,
+  make it sound human, de-AI, rewrite naturally.
+---
+
+# omd-humanize
+
+Natural writing is not text with detector bait removed. It is a person, in a specific
+situation, trying to change what a specific listener knows, feels able to do, or does next.
+Edit that discourse. Do not optimize for detector evasion, add mistakes, imitate a person,
+or manufacture quirky rhythm.
+
+## Hard laws
+
+1. **Freeze the evidence.** Preserve facts, numbers, names, verified claims, uncertainty,
+   and verbatim quotations. Never invent a promise, comparison, emotion, motive, personal
+   experience, customer, result, or degree of certainty. If an exact quote cannot stay
+   verbatim, remove it; never paraphrase it as a quote.
+2. **Preserve the job and register.** Chat remains dialogue, a support reply remains
+   support, an essay remains an essay, and documentation remains documentation. Formality,
+   language, accessibility needs, and the requested genre do not drift toward generic
+   marketing voice.
+3. **Edit the smallest coherent discourse unit.** Repair a sentence, exchange, paragraph,
+   or section that has one communicative job. Do not perform token-by-token synonym swaps;
+   they preserve the broken logic while making factual drift harder to see.
+4. **Do the requested work.** The first useful sentence carries the answer, decision, or
+   next action. Do not announce an answer before giving it, substitute an offer of help for
+   the help, or continue after the communicative job is complete.
+
+## Required input contract
+
+Identify these before rewriting:
+
+- **Speaker** — who is speaking and what authority they have;
+- **Listener** — who needs this and what context they already share;
+- **Situation** — what just happened or prompted the message;
+- **Intended change / next move** — what should become clearer or possible;
+- **Genre and register** — chat reply, UI state, landing page, essay, tutorial, policy,
+  support response, or another named form, including language and formality;
+- **Facts and quotes** — the allowed factual ledger, uncertainty, and exact quotations.
+
+In an OMD run, derive this contract from `.omd/copy-deck.md`: Voice contract `Audience`,
+`Language`, and `Register`, then each surface's `Main message`, `Supporting fact`, `Next
+action`, and `Claim refs`. Only `verified` facts may support shipped claims. `open` and
+`fixture` facts cannot ship. When speaker, listener, situation, intent, genre, register,
+fact status, or quote status is missing, return the gap to `omd-writer`; do not guess.
+
+## Choose one mode
+
+### Mode A — local repair
+
+Use local repair when the message already has a sound order: it answers the right question,
+each section has a distinct job, and the next move is clear. Rewrite only the smallest unit
+whose wording blocks that job. Typical repairs make the actor and action concrete, move a
+caveat next to its claim, remove a redundant restatement, or replace translation-shaped
+nominalization with a direct verb while preserving register.
+
+### Mode B — reconstruct from facts
+
+Use reconstruction only when the prompt has shaped the discourse itself: the response
+mirrors the request instead of answering it, explains its own plan before acting, repeats
+the same proposition under symmetrical headings, or buries a simple next move under
+exhaustive framing. Patching sentences cannot repair that order.
+
+Discard the generated outline, not the evidence. Rebuild from the verified fact ledger,
+voice contract, and the surface's real action/state. For non-OMD conversation, rebuild only
+from the supplied facts and established conversational context. Preserve every honest
+unknown. Never import a new claim merely to make the reconstruction sound complete.
+
+## Diagnose the discourse, not isolated tokens
+
+These are contextual root causes. A word or structure is not a verdict by itself.
+
+- **Ceremonial acknowledgement** delays the payload with thanks, praise, or agreement that
+  changes nothing. Keep acknowledgement when relationship repair, support, or a sensitive
+  event genuinely requires it; make it specific and brief.
+- **Request echo** repeats what the listener just said. Restatement is useful when confirming
+  a dangerous, ambiguous, legal, or multi-step instruction; otherwise answer directly.
+- **Answer narration** describes what the reply will cover before covering it. Tutorials and
+  long reference documents may need a map; a simple question does not.
+- **Deferred service** offers to investigate, draft, or help when the speaker can perform
+  that work now. Ask a question only for a real gap that changes the result.
+- **Scale mismatch** gives a taxonomy, lecture, or caveat wall to a small practical request.
+  Legal, medical, security, and safety-critical material may need explicit limits; place
+  each limit beside the claim it qualifies.
+- **Redundant recap** repeats a proposition in the title, opening, bullets, conclusion, or
+  CTA without adding a decision. Recap is legitimate in long tutorials, handoffs, and
+  accessibility-oriented instructions when it supports recall or safe completion.
+- **Performed empathy** names an emotion the speaker cannot know or uses a stock sympathy
+  line. Support writing may acknowledge an observed consequence; do not invent the person's
+  feelings.
+- **Template geometry** forces equal headings, matching paragraph sizes, repeated triads,
+  or balanced contrast clauses onto ideas that do not have equal weight. Keep lists and
+  parallel structure when the content is genuinely enumerable or comparable.
+- **Abstract agency** hides the actor and action inside nouns, passive layers, or
+  translation-shaped phrasing. Restore a concrete subject and verb unless the genre needs
+  the actor omitted for legal, scientific, or procedural precision.
+- **Automatic closing** adds a generic invitation after the answer is already complete.
+  Keep a closing action only when the listener needs a real escalation route or next step.
+
+## Language and surface judgment
+
+For Korean, choose the speech level from the genre and voice contract, then hold it. Product
+copy often uses 해요체 or 합니다체; essays, developer notes, dialogue, legal text, and quoted
+speech may require different registers. Treat repeated literal subjects, stacked particles,
+translation-shaped passive forms, connective punctuation, and nominal padding as symptoms
+only when they make this speaker sound unnatural in this situation. Korean connectives can
+carry real logic; do not delete them mechanically.
+
+For English, inspect hedging stacks, abstract nouns, formulaic openings, symmetrical contrast,
+and reflexive politeness in context. A policy caveat, support acknowledgement, or tutorial
+signpost may be doing necessary work. Keep it when removing it would reduce truth, safety,
+orientation, or care.
+
+UI copy is action/state language: say what happened, what remains true, and what the person
+can do next. Assistant dialogue uses established context and answers at the listener's
+altitude. Essays may retain unresolved thought and a personal cadence only when the supplied
+speaker genuinely owns that experience. Documentation favors stable terminology,
+prerequisites, and scan paths over conversational warmth.
+
+## Rewrite procedure
+
+1. Write the six input-contract fields. Mark unknowns; do not fill them creatively.
+2. Extract a factual ledger before editing. Include exact numbers, proper nouns, claim
+   status, uncertainty, and quotes.
+3. State the message's single job and the next move. Choose local repair or reconstruction.
+4. Rewrite in the chosen genre. Put the payload first, keep each proposition once, and place
+   evidence or caveats beside the claim they support.
+5. Compare the result against the factual ledger. Any added, removed, strengthened, or
+   weakened proposition is a failure. Quotes are byte-for-byte unchanged or absent.
+6. Read aloud for speaker/listener fit. Repair only genuine friction; do not add artificial
+   sentence-length variation or deliberate roughness.
+7. Stop when the job is done.
+
+## OMD ownership and invalidation
+
+`omd-humanize` diagnoses and proposes a rewrite; it does not bypass the copy owner. Only
+`omd-writer` changes `.omd/copy-deck.md`. After the writer's revision, run `omd copy --check`,
+then `omd-hand` synchronizes production source and rerenders. A changed shipped line, claim,
+or action invalidates the affected blind copy review and typography proof. Rerun the relevant
+proof instead of carrying an earlier approval forward.
+
+## Acceptance
+
+- The first useful sentence carries the payload.
+- Title, body, and CTA do not repeat the same proposition.
+- A concrete actor performs a concrete action where the genre permits it.
+- Caveats and uncertainty remain honest and sit beside the claims they qualify.
+- The next move is explicit when one exists; there is no empty closing offer.
+- The text sounds natural when read aloud without manufactured rhythm or fake quirks.
+- The factual-ledger diff is clean, and every shipped OMD claim still cites `verified` facts.
+
+Return the rewritten result by default. Do not lead with a violation inventory. Provide a
+brief audit only when the user requests one or when filling the durable Humanize audit in
+the copy deck.

package/src/skills/omd-scout/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: omd-scout
+description: >-
+  Build a measured reference board without designing anything: whole pages for feel,
+  tight selectors for component anatomy, typography studies, motion studies, image refs
+  for the unrenderable. Use when the user asks for references, inspiration, benchmarks,
+  or "how do good sites do X" — standalone, before or without a build.
+  Triggers: 레퍼런스 찾아줘, 레퍼런스 수집, 참고 사이트, 벤치마킹, find references,
+  inspiration board, how do other sites do.
+---
+
+# omd-scout
+
+A reference board, measured instead of pinned. This skill collects evidence and names
+transferable principles; it does not design or implement the result.
+
+Spawn `omd-scout` with the concept (ask one short question only when neither the request nor
+`.omd/frame.md` supplies one), the component inventory, working directory, and user URLs.
+User URLs are captured first and marked `--from-user`.
+
+## Coverage contract
+
+Build for decision coverage, not capture counts. Before searching, list the decisions the
+later design must make and the components it must support. The board is complete only when
+it contains useful, non-duplicate evidence for every applicable category:
+
+- domain conventions and user expectations;
+- direct competitors and meaningful alternatives;
+- first-party or user/community language;
+- typography and voice;
+- motion when the concept or interaction actually needs it;
+- every required component or state whose anatomy is uncertain.
+
+There is no minimum query count, capture quota, famous-site quota, or mandatory award
+gallery. A small board with complete, independent evidence is better than a large gallery of
+near-duplicates. If a category is irrelevant, record why. If evidence remains weak or
+contradictory, report the gap and uncertainty instead of filling a slot with decoration.
+
+Use the narrowest useful capture:
+
+```bash
+omd ref add <user-url> --as <name> --from-user
+omd ref add <url> --as <name>
+omd ref add <url> --as <name> --selector ".component"
+omd ref add <url> --as <name> --selector ".component" --blueprint
+omd ref add <image-url> --as <name> --image
+omd ref principles <url> --as <name> --add "..."
+omd ref list
+```
+
+Whole-page captures establish rhythm or product feel; tight selectors establish component
+anatomy; type and motion studies establish measured behavior; image references support only
+what cannot be rendered. A blueprint is allowed only for an explicitly requested exact
+component transplant or a structurally equivalent component problem. Structure may
+transfer; skin and pixels do not.
+
+## Evidence quality and contamination
+
+Prefer first-party product sources and direct user/community evidence over SEO summaries.
+Label source trust, uncertainty, and whether evidence is independent or derivative. Reject
+a non-user source with two or more slop signals. Keep a user-provided contaminated source
+only as a named anti-reference. Drop kin at similarity `>= .85`; a cluster of related pages
+is one evidence family, not independent corroboration. A blocked page is not retried; use an
+honest image/discourse fallback or discard it.
+
+Every retained capture records:
+
+- the decision or coverage gap it answers;
+- measured invariants and the reason they matter;
+- what contradicts the concept;
+- source trust and uncertainty;
+- the token, component, motion, voice, or composition question it may inform.
+
+Never describe a page for imitation, show reference screenshots to the builder, copy visual
+skin, or turn award status into evidence. Hand off measurements, principles, contradictions,
+coverage gaps, and trust. Raw captures remain under `.omd/refs/`; downstream agents receive
+only the sanitized evidence summary required for their decision.