@3xhaust/oh-my-design 0.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/LICENSE +21 -0
  2. package/README.ko.md +282 -0
  3. package/README.md +282 -0
  4. package/adapters/build.ts +184 -0
  5. package/adapters/claude.ts +111 -0
  6. package/adapters/codex.ts +68 -0
  7. package/adapters/tokens.ts +21 -0
  8. package/adapters/tool-map.json +7 -0
  9. package/bin/omd-install.ts +76 -0
  10. package/bin/omd.ts +1774 -0
  11. package/core/asset-sourcing/index.ts +187 -0
  12. package/core/coach/index.ts +98 -0
  13. package/core/composition/app-shell-workbench.md +168 -0
  14. package/core/composition/asymmetric-diagonal-grid.md +178 -0
  15. package/core/composition/bento-grid.md +223 -0
  16. package/core/composition/editorial-index-labels.md +173 -0
  17. package/core/composition/form-wizard-stepper.md +132 -0
  18. package/core/composition/master-detail-flow.md +129 -0
  19. package/core/composition/section-inversion.md +182 -0
  20. package/core/composition/sidebar-margin-annotation.md +184 -0
  21. package/core/composition/split-screen-hero.md +224 -0
  22. package/core/composition/sticky-sidebar-scroll.md +219 -0
  23. package/core/composition/typographic-hero.md +100 -0
  24. package/core/composition-contract/index.ts +233 -0
  25. package/core/composition-contract/visual-richness.ts +101 -0
  26. package/core/config/index.ts +27 -0
  27. package/core/copy/index.ts +296 -0
  28. package/core/craft/finish-pass.md +356 -0
  29. package/core/craft/index.ts +33 -0
  30. package/core/design/index.ts +581 -0
  31. package/core/design/interaction-states.ts +189 -0
  32. package/core/eval-harness/index.ts +225 -0
  33. package/core/evidence/final.ts +444 -0
  34. package/core/evidence/task.ts +459 -0
  35. package/core/figma/client.ts +312 -0
  36. package/core/figma/diff.ts +261 -0
  37. package/core/figma/responsive.ts +310 -0
  38. package/core/figma/system.ts +466 -0
  39. package/core/figma/types.ts +185 -0
  40. package/core/frame/check-ux.ts +180 -0
  41. package/core/frame/index.ts +39 -0
  42. package/core/frame/write.ts +168 -0
  43. package/core/graphics/css-illustration-primitives.md +189 -0
  44. package/core/graphics/duotone-image-presets.md +173 -0
  45. package/core/graphics/gradient-mesh.md +178 -0
  46. package/core/graphics/noise-grain-texture.md +150 -0
  47. package/core/graphics/placeholder-policy.md +185 -0
  48. package/core/graphics/svg-geometric-patterns.md +145 -0
  49. package/core/history/index.ts +39 -0
  50. package/core/install/detect.ts +32 -0
  51. package/core/install/install.ts +321 -0
  52. package/core/install/patch-claude.ts +109 -0
  53. package/core/install/patch-codex.ts +82 -0
  54. package/core/interaction/index.ts +101 -0
  55. package/core/interaction/recipes/signature-lighting.md +203 -0
  56. package/core/ir/dom.ts +352 -0
  57. package/core/ir/normalize.ts +177 -0
  58. package/core/motion/easing.md +151 -0
  59. package/core/motion/energy.ts +188 -0
  60. package/core/motion/recipes/image-hover-distortion.md +198 -0
  61. package/core/motion/recipes/magnetic-hover.md +229 -0
  62. package/core/motion/recipes/marquee.md +202 -0
  63. package/core/motion/recipes/number-counter.md +242 -0
  64. package/core/motion/recipes/page-loader.md +240 -0
  65. package/core/motion/recipes/parallax.md +233 -0
  66. package/core/motion/recipes/scroll-reveal.md +210 -0
  67. package/core/motion/recipes/section-color-inversion.md +217 -0
  68. package/core/motion/recipes/split-text-entrance.md +222 -0
  69. package/core/motion/recipes/stagger-orchestrator.md +227 -0
  70. package/core/motion/recipes/sticky-scene-transition.md +246 -0
  71. package/core/motion/recipes/view-transitions.md +239 -0
  72. package/core/probe/index.ts +186 -0
  73. package/core/probe/schema.json +46 -0
  74. package/core/protocol/composition-contract.md +192 -0
  75. package/core/protocol/copy-deck.md +96 -0
  76. package/core/protocol/human-design-loop.md +447 -0
  77. package/core/protocol/slop-review.md +71 -0
  78. package/core/ref/batch.ts +94 -0
  79. package/core/ref/blueprint.ts +199 -0
  80. package/core/ref/distance.ts +225 -0
  81. package/core/ref/invariants.ts +162 -0
  82. package/core/ref/signal.ts +37 -0
  83. package/core/ref/store.ts +122 -0
  84. package/core/render/index.ts +607 -0
  85. package/core/rules/attribution.ts +159 -0
  86. package/core/rules/builtin/contrast.yaml +8 -0
  87. package/core/rules/builtin/focus.yaml +8 -0
  88. package/core/rules/builtin/hit-area.yaml +8 -0
  89. package/core/rules/builtin/ko.yaml +6 -0
  90. package/core/rules/builtin/motion.yaml +80 -0
  91. package/core/rules/builtin/slop.yaml +365 -0
  92. package/core/rules/builtin/spacing.yaml +9 -0
  93. package/core/rules/builtin/system.yaml +42 -0
  94. package/core/rules/builtin/token.yaml +8 -0
  95. package/core/rules/builtin/ux.yaml +125 -0
  96. package/core/rules/engine.ts +88 -0
  97. package/core/rules/leakage.ts +72 -0
  98. package/core/rules/motion-spec.ts +204 -0
  99. package/core/site/index.ts +100 -0
  100. package/core/slop/index.ts +427 -0
  101. package/core/slop/text-slop.ts +220 -0
  102. package/core/source-seal/index.ts +174 -0
  103. package/core/stack/index.ts +53 -0
  104. package/core/target/index.ts +183 -0
  105. package/core/theory/color.md +285 -0
  106. package/core/theory/components.md +272 -0
  107. package/core/theory/craft.md +270 -0
  108. package/core/theory/expressive.md +213 -0
  109. package/core/theory/imagegen.md +105 -0
  110. package/core/theory/layout.md +159 -0
  111. package/core/theory/motion.md +283 -0
  112. package/core/theory/typography.md +134 -0
  113. package/core/theory/ux.md +580 -0
  114. package/core/theory/voice.md +595 -0
  115. package/core/types.ts +684 -0
  116. package/package.json +40 -0
  117. package/src/agents/composer.agent.yaml +174 -0
  118. package/src/agents/eye.agent.yaml +208 -0
  119. package/src/agents/framer.agent.yaml +52 -0
  120. package/src/agents/glance.agent.yaml +19 -0
  121. package/src/agents/hand.agent.yaml +200 -0
  122. package/src/agents/scout.agent.yaml +71 -0
  123. package/src/agents/sketch.agent.yaml +64 -0
  124. package/src/agents/typesetter.agent.yaml +52 -0
  125. package/src/agents/writer.agent.yaml +63 -0
  126. package/src/skills/omd-coach/SKILL.md +40 -0
  127. package/src/skills/omd-critique/SKILL.md +77 -0
  128. package/src/skills/omd-figma/SKILL.md +256 -0
  129. package/src/skills/omd-humanize/SKILL.md +160 -0
  130. package/src/skills/omd-scout/SKILL.md +77 -0
  131. package/src/skills/omd-ultradesign/SKILL.md +521 -0
@@ -0,0 +1,595 @@
1
+ # Voice — decision material
2
+
3
+ Copy reveals whether its language fits the speaker, listener, surface, and task before visual
4
+ polish can rescue it. A forced line break, repeated cadence, or empty hedge can prompt a
5
+ contextual review, but no individual signal establishes authorship. This file records the
6
+ jobs those patterns can obstruct and the repairs that preserve evidence.
7
+
8
+ ---
9
+
10
+ ## Statistical observations are not writing instructions
11
+
12
+ Generated-text studies have measured aggregate differences in predictability, sentence
13
+ length, and paragraph complexity within particular datasets. Those distributions can
14
+ describe a corpus; they cannot establish who wrote an individual passage or whether it does
15
+ its job. Genre, language, accessibility needs, short UI labels, and technical constraints can
16
+ all produce the same measurements.
17
+
18
+ Do not manufacture sentence-length variance, surprise, typos, asides, or roughness to imitate
19
+ a distribution. Rhythm follows the speaker's thought and the surface's job. When prose feels
20
+ mechanical, inspect the discourse: repeated propositions, abstract agency, prompt mirroring,
21
+ misplaced caveats, or a register that does not fit the relationship. Repair that cause and
22
+ let sentence shape follow. Detector scores and stylometric thresholds never gate shipping.
23
+
24
+ ---
25
+
26
+ ## How people actually read on the web
27
+
28
+ The finding that shaped modern web writing came from Jakob Nielsen and John Morkes in 1997.
29
+ In their study of how users approached web pages, 79 percent of test users always scanned
30
+ any new page — only 16 percent read word by word. Twenty-three years later, Nielsen's 2020
31
+ follow-up confirmed the proportion had not moved. Scanning is not a failure mode; it is the
32
+ default mode of a reader whose attention is distributed across millions of competing pages.
33
+
34
+ The same pair published the implications in "Concise, SCANNABLE, and Objective: How to Write
35
+ for the Web" (Morkes and Nielsen, 1997). Testing five writing styles against a control, they
36
+ found the concise version scored 58% higher in measured usability, the scannable version 47%
37
+ higher, and the objective version (no promotional language) 27% higher. A site that was all
38
+ three simultaneously scored 124% higher. A follow-up rewriting Sun.com pages produced 159%
39
+ improvement. These are not marginal effects; they are the largest usability gains in the
40
+ literature for a single intervention class.
41
+
42
+ Nielsen's 2006 eye-tracking study of 232 users across thousands of pages documented the
43
+ F-pattern: a full sweep of the first line, a shorter sweep of a second line, then a vertical
44
+ scan down the left edge. The pattern is a failure state — it emerges when content lacks
45
+ visual hierarchy and the reader falls back to a heuristic. The design response is not to
46
+ format text to fit the F; it is to give the reader entry points that break the fallback.
47
+
48
+ What these studies mean for sentence construction:
49
+
50
+ **Front-load information.** The first sentence of a paragraph and the first clause of a
51
+ sentence carry disproportionate weight. If the important claim is buried after a preamble,
52
+ the scanner never sees it. The inverted pyramid — conclusion first, support after — is not
53
+ a newspaper convention; it is the writing shape that matches how web users extract value.
54
+
55
+ **One idea per paragraph.** A paragraph that opens with claim A and closes with claim B is
56
+ two paragraphs. Splitting them is not padding; it is giving each claim the surface area to
57
+ be scanned and absorbed independently.
58
+
59
+ **Concrete nouns over abstract nominalizations.** "The facilitation of user onboarding" and
60
+ "helping people get started" convey the same claim. The second is scannable; the first
61
+ requires parsing. Abstract nouns — facilitation, optimisation, utilisation — slow processing
62
+ and carry no additional precision. Every nominalization is a candidate for replacement with
63
+ a verb or a specific noun.
64
+
65
+ ---
66
+
67
+ ## Plain language is not dumbing down
68
+
69
+ Daniel Oppenheimer's 2006 study "Consequences of Erudite Vernacular Utilized Irrespective
70
+ of Necessity" (*Applied Cognitive Psychology*, 20(2), 139–156) ran five experiments with
71
+ Stanford students, manipulating the vocabulary complexity of texts and measuring the authors'
72
+ perceived intelligence. The result reversed the folk assumption: as complexity increased,
73
+ estimated author intelligence decreased. The mechanism is processing fluency — difficult
74
+ text feels effortful to read, and the reader attributes that effort to the writer's
75
+ unclear thinking rather than to the word choice. The effect held regardless of essay quality
76
+ and regardless of readers' prior expectations.
77
+
78
+ Plain language is the confident register. It is the register of a person who understands
79
+ the subject well enough to explain it without armour. Mailchimp's public content style guide
80
+ (styleguide.mailchimp.com) names this "plainspoken" and defines it as stripping away the
81
+ hyperbolic language, upsells, and over-promises that the reader has learned to distrust —
82
+ not because simplicity is good in itself, but because clarity is what trust is built on.
83
+
84
+ 37signals states the same principle in their communication guide: "If your words can be
85
+ perceived in different ways, they'll be understood in the way which does the most harm."
86
+ Plain writing reduces the number of ways a sentence can be understood. That reduction is a
87
+ quality, not a constraint.
88
+
89
+ Condition → choice → reason: when a sentence contains a long Latinate noun where a
90
+ shorter verb would serve — "provide an indication of" → "indicate", "make a determination"
91
+ → "decide", "in the event that" → "if" — replace it. The test is not whether the long form
92
+ is correct but whether the short form loses any precision. In the overwhelming majority of
93
+ cases, it does not.
94
+
95
+ ---
96
+
97
+ ## The voice chart: writing from product principles
98
+
99
+ Torrey Podmajersky's *Strategic Writing for UX* (O'Reilly, 2019) introduces the voice chart
100
+ as the instrument that connects product principles to copy decisions. The chart holds rows
101
+ for vocabulary, verbosity, grammar, and concepts — filled in for each dimension by asking
102
+ what the product principle demands of the words, not what sounds nice. A financial product
103
+ whose principle is "trustworthy" chooses precise vocabulary over colloquial; a product whose
104
+ principle is "approachable" accepts shorter sentences and native vocabulary over formal
105
+ constructions. Podmajersky's formulation: "These principles define what the experience is
106
+ trying to be to the people who use it. Then, the voice can do its job of conveying those
107
+ product principles with every word."
108
+
109
+ The voice chart makes copy decisions auditable. Without it, every copy choice is a taste
110
+ decision — and taste decisions are re-litigated on every page, by every person who touches
111
+ the product. With it, the question becomes: does this sentence match the registered
112
+ voice dimensions? That is a question with a testable answer.
113
+
114
+ Condition → choice → reason: before writing a word of copy, name the product principle
115
+ each section is serving. When no principle can be named, the copy is decoration; decoration
116
+ is the first thing the scanner skips.
117
+
118
+ ---
119
+
120
+ ## The review-mining move
121
+
122
+ Joanna Wiebe at Copyhackers documented what she calls the voice-of-customer method: instead
123
+ of writing copy on a blank page, mine the language that real users have already written —
124
+ in reviews, support tickets, forum threads, comment sections — and use their phrasing
125
+ directly. The argument is that the customer names the value of the product more precisely
126
+ than the copywriter can, because the customer experienced the problem before the solution
127
+ existed and reaches for the words that match that experience.
128
+
129
+ The method is a search operation. Identify the exact problem your product solves. Find
130
+ online communities — reviews, subreddits, Help forum threads — where people describe that
131
+ problem in their own words. The phrases that appear repeatedly, with emotional precision,
132
+ are the phrases the copy should use or echo. The user who writes "I used to spend three
133
+ hours a week reconciling this manually" has handed you a sentence. The copy that quotes
134
+ their situation back to them is the copy that converts.
135
+
136
+ This connects directly to the scout's community captures. A Reddit thread where users argue
137
+ about exactly this product category, a Hacker News comment naming why a redesign failed —
138
+ these are not sentiment data. They are voice data. The scout captures them; the hand uses
139
+ them. A voice study that records how a site writes is the positive model; the community
140
+ captures record the phrases the audience already uses for the problem.
141
+
142
+ ---
143
+
144
+ ## Korean copy: 한국어 카피의 목소리
145
+
146
+ Korean product copy requires decisions that English-language guidance does not settle.
147
+ Literal transfer can produce translation-shaped prose, so judge the result against its Korean
148
+ speaker, listener, situation, and register rather than inferring its origin.
149
+
150
+ ### Speech-level commitment: choose one and hold it
151
+
152
+ Two common written registers in Korean product copy are 해요체 (하다 → 해요, 됩니다 → 돼요)
153
+ and 합니다체 (하다 → 합니다, 됩니다 → 됩니다). They can imply different relationships:
154
+ 합니다체 often supports institutional precision, while 해요체 often supports conversational
155
+ warmth. Neither is a universal product default; choose from the voice contract, audience,
156
+ situation, and required authority.
157
+
158
+ Toss committed to 해요체 across every string in its product and published the rule
159
+ explicitly: all copy uses 해요체, without exception, regardless of context or screen.
160
+ Their stated reason is consistency of experience — 합니다체 anywhere breaks the register
161
+ the rest of the product has established. The rule also extends to avoiding over-polite forms
162
+ (~시겠어요?, ~께) that amplify formality past what the relationship calls for.
163
+
164
+ What the `SLOP-KO-REGISTER-MIX` rule detects — 해요체 and 합니다체 alternating within one
165
+ text node — is a review candidate. It may expose unplanned register drift, or it may be
166
+ required by quoted speech or a deliberate change of speaker. Context decides.
167
+
168
+ Condition → choice → reason: before writing Korean surface copy, record its speech level in
169
+ the voice contract. Hold it across strings that share one speaker and relationship, including
170
+ applicable error, empty, and action states. When the register changes, identify the changed
171
+ speaker or situation rather than treating inconsistency as personality.
172
+
173
+ ### Vocabulary temperature: 고유어 over 한자어 where precision allows
174
+
175
+ Korean has two vocabulary strata available for almost any concept: native Korean (고유어)
176
+ and Sino-Korean (한자어). Most product copy defaults to Sino-Korean because it feels
177
+ professional and precise. This instinct produces text that is correct, stiff, and forgettable.
178
+
179
+ Toss's 8 writing principles include "Easy to speak" — their test is whether the sentence
180
+ sounds wrong when said aloud, not whether it looks wrong in print. They cite 한자어 and
181
+ literary 문어체 constructions as the primary cause of copy that passes a proofreading
182
+ read but sounds like documentation. Examples from their practice: 송금이 완료되었습니다
183
+ becomes 5000원을 보냈어요 — "송금" (Sino-Korean for remittance) replaced by "보내다" (native
184
+ verb for send), "완료되었습니다" (formal Sino-Korean completion) replaced by "보냈어요"
185
+ (native past tense in 해요체). The semantic content is identical; the temperature is
186
+ completely different.
187
+
188
+ The working vocabulary test: say the sentence aloud. Does it sound like something a person
189
+ would say to a friend explaining what just happened? If not, identify the Sino-Korean
190
+ construction and replace it with the native equivalent. "결제 진행" → "결제 중". "이용
191
+ 가능합니다" → "쓸 수 있어요". "확인 후 진행하세요" → "확인하고 다음으로 가세요". Each
192
+ substitution costs no precision and removes the institutional chill that Sino-Korean carries.
193
+
194
+ ### One sentence, one useful job
195
+
196
+ Toss's principle 4 — Focus on key message — is a useful test for compact product surfaces:
197
+ one short UI string usually carries one primary job that can be read in a breath. Korean's
198
+ agglutinative structure tempts long sentences because each extension costs only a morpheme,
199
+ and the grammatical seams are invisible in a way that English subordination is not. The
200
+ more jobs a compact string carries, the harder it becomes to scan.
201
+
202
+ Use breath as contextual evidence, not a universal sentence rule. A legal notice, tutorial,
203
+ or technical explanation may need a longer sentence. When a compact surface combines
204
+ unrelated jobs, split at the change; retain a connective when it carries a real logical
205
+ relationship that juxtaposition would lose.
206
+
207
+ ### What Korean products actually sound like
208
+
209
+ Successful Korean consumer products such as Toss, 당근, and Kakao show that consistency is
210
+ not the same as informality. Their compact action and state copy is precise within its chosen
211
+ register. Heroes often lead with the user's change; documentation, comparisons, and feature
212
+ details may explain mechanism when mechanism is the useful fact.
213
+
214
+ 배민 (Baemin) operates in a distinct creative register — warm, witty, deliberately playful —
215
+ but the underlying commitment is the same: a consistent voice that was designed and held,
216
+ not allowed to drift. Their UX writing interview at bcut.baemin.com describes the first
217
+ UX writer's mandate as "ensuring the text inside the app communicates clearly with users
218
+ and protecting consistency." The register is brand-specific; the structural commitment is
219
+ universal.
220
+
221
+ ### Document-structure narration: write the content, not that content is coming
222
+
223
+ Korean product copy can lose its job when it narrates the document before presenting it.
224
+ "아래는 그 기록이에요" (below is the record), "다음은 기능 목록입니다"
225
+ (the following is the feature list) — these sentences announce the organisation of what
226
+ follows rather than delivering it. A tutorial or long document may need signposting; a small
227
+ product surface usually benefits from starting with the fact or action itself.
228
+
229
+ `SLOP-KO-SIGNPOST` fires on the deterministic patterns: `아래는 … 기록/내용/목록/정리` and
230
+ `다음은 … 입니다/이에요`. The fix is deletion: remove the announcing sentence and start with
231
+ the content it was announcing. "아래는 그 기록이에요." → delete it; begin with the first item.
232
+
233
+ The negative to hold in mind: "아래 버튼을 누르세요" does not fire. 아래 used as a spatial
234
+ adverb (without the topic marker 는) is navigation copy, not structural narration.
235
+
236
+ ### Calibration evidence: what the measured gap between human and pipeline prose reveals
237
+
238
+ The following lessons come from a direct calibration: a 16,000-character Korean personal tech
239
+ essay by Evan Moon (evan-moon.github.io/2020/12/29/2020-retrospective/, published December 2020,
240
+ fully human-authored) was used as the baseline. A parallel version covering the same facts was
241
+ written by following voice.md and the humanize skill rules faithfully. The two versions were
242
+ measured against the same metrics. The gaps name what our rules actively get wrong.
243
+
244
+ **Measured diff table (N=26–36 sentences per version, character lengths exclude spaces):**
245
+
246
+ | Metric | Human essay | Our version |
247
+ |---|---|---|
248
+ | Sentence length min | 8 chars | 8 chars |
249
+ | Sentence length max | 114 chars | 48 chars |
250
+ | Sentence length mean | 50.4 chars | 19.9 chars |
251
+ | Sentence length σ | 26.1 | 9.8 |
252
+ | Ending diversity (unique/total) | 0.86 | 0.96 |
253
+ | Connective rate (per sentence) | 0.42 | 0.00 |
254
+ | C-11 violations (connective+comma) | 1 | 0 |
255
+ | Parenthetical asides | 6 in full article | 0 |
256
+ | Unresolved uncertainty markers | 5 | 0 |
257
+
258
+ **Lesson 1 — Register context comes before a speech-level default**
259
+
260
+ The sampled human essay uses the informal narrative register (-다 style) throughout: 해였다,
261
+ 것 같다, 생각이었다, 모르겠다. None of these are 해요체 or 합니다체. Korean personal essays,
262
+ 회고글, and reflective blog posts are written in this register — it is the written voice of a
263
+ person narrating their own experience, not the addressed voice of a product speaking to a user.
264
+
265
+ Applying 해요체 to every Korean genre can produce a newsletter register: warm,
266
+ present-tense, and second-person-inflected, which may fit one UI voice but not a formal
267
+ service, first-person retrospective, or developer note.
268
+
269
+ Condition → choice → reason: identify speaker, listener, situation, genre, and authority,
270
+ then choose 해요체, 합니다체, -다 style, or another evidenced register in the voice contract.
271
+ Product copy has no universal speech-level exception to that decision.
272
+
273
+ **Lesson 2 — Connective overcorrection: the tell is the comma, not the connective**
274
+
275
+ The sampled human essay uses connectives at a rate of 0.42 per sentence — 15 connectives
276
+ across 36 sentences, including 하지만, 그래서, 그런데, 물론, 또한, 사실, 결국. Not one
277
+ is followed by a comma (C-11 count: 1, a naturally-occurring case). The human connective
278
+ rate is high because connectives carry logical structure; they are not AI tells by themselves.
279
+
280
+ The pipeline version, shaped by the SKILL.md rule against "connector abuse," produced zero
281
+ connectives across 26 sentences. That is not more human — it is a different kind of abnormal.
282
+ Abrupt juxtaposition without connectives reads as choppy, clipped, produced by a sentence-by-
283
+ sentence generator rather than a mind that knows where the paragraph is going.
284
+
285
+ What the C-11 rule identifies is the narrow pattern of a connective immediately followed by
286
+ a comma — 하지만, / 그러나, / 또한, / 따라서, — for contextual review. The rule does not
287
+ say that the author is known or that all connectives should be removed.
288
+
289
+ Condition → choice → reason: clustering and punctuation can make connective use feel
290
+ mechanical, while one connective may mark a necessary logical turn. Ask whether each opening
291
+ expresses a real relationship. Repair redundant structure, not the words as a class.
292
+
293
+ **Lesson 3 — Parenthetical asides: a positive model our rules never named**
294
+
295
+ The sampled essay contains six parenthetical asides across 16,000 characters — roughly one per
296
+ 1,000 characters, or once every three to four paragraphs: "(살면서 노래방을 이렇게 안 가본 게
297
+ 처음…)", "(결국 이러다가 번아웃이 왔었지만, 습관은 잘 안 고쳐지더라…)", "(그리고 스스로 뭔가
298
+ 꼰대 같다는 생각이 들어서 이걸 깨닫고 한동안 우울했었다)". These are self-interruptions —
299
+ second thoughts, humor, and corrections that carry information the main sentence cannot.
300
+
301
+ The pipeline produces zero. The tells list names what to remove; it has no positive model for
302
+ this form. An essay with no parenthetical asides in 3,000+ characters is measurably flatter
303
+ than the human baseline.
304
+
305
+ Condition → choice → reason: in essayistic Korean prose, preserve a supplied second thought
306
+ when it changes the meaning or carries honest uncertainty. Do not add an aside merely because
307
+ the passage lacks one; a manufactured interruption is no more natural than a manufactured
308
+ cadence.
309
+
310
+ **Lesson 4 — σ and unresolved uncertainty: preserve what remains unresolved**
311
+
312
+ The human essay's sentence-length σ was 26.1; the pipeline's was 9.8. The maximum sentence
313
+ length in the human essay was 114 characters (no spaces); the pipeline capped at 48. The old
314
+ burstiness instruction was the wrong abstraction. The human passage follows thought instead
315
+ of managing a sentence-length pattern; its measurements describe one sample and are not a
316
+ recipe to reproduce.
317
+
318
+ The sampled human essay closed its mentoring section with: "하지만 아직도 잘 모르겠다." Thirteen
319
+ characters. The pipeline produced: "이게 올해가 남긴 가장 큰 질문이에요." That is a packaged
320
+ takeaway. It names the lesson; it does not live in the uncertainty. The human's 13-character
321
+ sentence is more trustworthy precisely because it refuses to resolve what has not been resolved.
322
+
323
+ The full article closed with: "2020년에는 결국 이렇게 답을 찾지 못한 질문으로 회고를 마무리하지만,
324
+ 내년 2021년 회고에는 이 질문과 고민에 대한 답을 찾아서 회고에 적는 것을 목표로 잡아야겠다." The
325
+ human commits to finding the answer next year rather than having found it this year.
326
+
327
+ Condition → choice → reason: when an essay section ends, ask whether a tidy conclusion is
328
+ honest or performed. A genuine takeaway — something the writer actually learned and can state
329
+ — earns the closure. A resolution that smoothes over ongoing uncertainty changes the claim.
330
+ If the answer does not exist yet, retain that uncertainty instead of packaging a lesson.
331
+
332
+ ### Uniform sentence endings and not-X-but-Y: pre-handoff checks, not linter rules
333
+
334
+ Two Korean patterns require contextual pre-handoff review and cannot become safe
335
+ deterministic rules:
336
+
337
+ **Three or more consecutive identical sentence-final endings** (이에요./이에요./이에요. or
338
+ 합니다./합니다./합니다.) may make prose feel mechanically parallel in context. However,
339
+ product benefit lists deliberately use parallel endings: "빠릅니다.
340
+ 정확합니다. 쉽습니다." is valid copy that would false-positive on every legitimate feature
341
+ section. A linter rule would fire on too much legitimate writing to be trusted.
342
+
343
+ Pre-handoff check: if adjacent sentences share an ending, ask whether the ideas are truly
344
+ parallel. Keep the form when it supports comparison or recall. If sameness hides a change in
345
+ communicative job, repair that sentence's job rather than forcing a different ending.
346
+
347
+ **The not-X-but-Y construction** (`~게 아니라 ~했어요` / `~이 아니라 ~입니다`) can become
348
+ performed contrast when no real distinction supports it. It also appears in legitimate copy:
349
+ a brand that deliberately contrasts itself with a
350
+ category norm ("빠른 게 아니라 정확합니다") uses this construction with intent. No narrow
351
+ regex distinguishes the cases reliably.
352
+
353
+ Pre-handoff check: when this construction appears in the hero or opening paragraph, ask
354
+ whether the contrast is a designed claim (cite it in decisions.md with the brand reason)
355
+ or a hedge that weakens the useful claim. Delete empty hedges; keep designed contrasts. "AI가 만든
356
+ 게 아니라, 사람이 썼어요" as a self-description of the tool is a hedge; "비싼 게 아니라
357
+ 오래 씁니다" as a product claim is a designed contrast.
358
+
359
+ Neither pattern has an `omd check` rule. Both belong on the hand's pre-handoff review pass.
360
+
361
+ Translated English marketing is the loudest failure mode. The sentence structure of
362
+ English product copy — subject, action verb, object, benefit clause — does not map cleanly
363
+ onto Korean's SOV order or its topic-comment preference. Copy that was conceived in English
364
+ and translated reads as translated: the particle choices are safe rather than native, the
365
+ nominalisations are abundant, and the rhythm is wrong in a way that fluent readers feel
366
+ before they can name it. The correct direction is to write the Korean sentence a Korean
367
+ product would have written first, not to translate the English sentence that would have
368
+ appeared on an English-language version of the same screen.
369
+
370
+ ---
371
+
372
+ ## Register: diagnose fit, not origin
373
+
374
+ Web, product, and assistant copy can drift into a medium-formal register that sounds like a
375
+ support FAQ edited by a committee. The useful question is not who wrote it, but whether that
376
+ register fits this speaker, listener, situation, and surface.
377
+
378
+ A 2025 study that fine-tuned Llama, Qwen, and Mistral-Nemo models toward natural
379
+ responses (arxiv 2501.05032v1, "Enhancing Human-Like Responses in Large Language Models")
380
+ identified the primary register failures: self-referential disclaimers, impersonal
381
+ deflection, over-structured formatting, and "formal and impersonal" phrasing that is
382
+ "structured, clear, and precise, but lacks the warmth and spontaneity of natural human
383
+ conversation." The fine-tuned models won blind human ratings at 79–90% preference rates;
384
+ general benchmark accuracy was unchanged. The lesson: formality should be chosen, not
385
+ defaulted into.
386
+
387
+ A register-aware linguistic evaluation (arxiv 2605.23651, "How Human-Like Are Large
388
+ Language Models? A Register-Aware Linguistic Evaluation Framework") measured the
389
+ statistical gap between LLM output and human writing across five registers, including
390
+ instructive online text — the closest analogue to product and help copy. Consistent
391
+ findings: models over-produce nominalisations, favor longer words, inflate attributive
392
+ adjectives, and stack present-participle clause constructions ("helping teams manage",
393
+ "allowing users to see"). Human instructive copy scores higher on Biber's Overt Expression
394
+ of Persuasion dimension and is more lexically variable. The model's version is less varied
395
+ and less authoritative, not more.
396
+
397
+ ### The self-introduction cadence
398
+
399
+ In product hero copy, "X is a platform that helps teams Y and Z" can merely restate the
400
+ brief instead of giving the reader a useful change or distinction. The construction is not
401
+ an authorship signal and remains appropriate when a comparison, documentation page, tooltip,
402
+ or feature detail genuinely needs category and mechanism.
403
+
404
+ Condition → choice → reason: when a hero opens with "[Product] is a [category noun] that
405
+ [verb]s you", ask whether category or mechanism is the useful fact. If not, lead with the
406
+ verified user change or distinction. Keep the mechanism where it answers the reader's real
407
+ question.
408
+
409
+ The same cadence appears in Korean as "X는 Y를 도와주는 플랫폼이에요" or "X는 Z를 관리할 수
410
+ 있는 도구예요". The pattern is identical: the product introduces itself by naming its own
411
+ mechanism. Rewrite from the user's change: "월요일 빌드는 제때 나가요" rather than "X는
412
+ 빌드 관리를 도와드리는 플랫폼이에요".
413
+
414
+ ### Reflexive over-politeness
415
+
416
+ Reflexive politeness such as "Please feel free to", "We'd be happy to help", and "Don't
417
+ hesitate to reach out" can import a helpdesk register into a surface that needs direct
418
+ action. Support contexts may need care and an escalation route; decorative politeness does
419
+ not replace either.
420
+
421
+ Condition → choice → reason: when the polite clause adds no relationship or safety value,
422
+ write the action directly. Keep specific care or escalation language when the situation
423
+ requires it.
424
+
425
+ ### Uniform formality regardless of product voice
426
+
427
+ A NAACL 2024 benchmark study (DialogBench, aclanthology.org/2024.naacl-long.341) found
428
+ that assistant-AI instruction tuning can actively weaken emotional naturalness — the
429
+ positioning trains the model toward uniform helpfulness, which erases the register
430
+ variation a specific product voice requires. A fintech product designed to feel like a
431
+ knowledgeable friend and a legal SaaS that wants institutional precision both receive the
432
+ same medium-formal output if the writer does not actively set the dial.
433
+
434
+ Condition → choice → reason: read the product's voice study before writing a word. Then
435
+ choose a register that is measurably lower or higher than the default formal medium.
436
+ "Lower" is not "chatty" — it means committing to vocabulary the product's actual users
437
+ use, at the warmth level the product's principles demand. The voice chart (Podmajersky)
438
+ is the tool that makes this concrete and auditable.
439
+
440
+ ### Over-nominalization and present-participle clause stacking
441
+
442
+ The register-aware study (arxiv 2605.23651) identified two structural tells in LLM
443
+ instructive text that appear below the level of word choice: over-nominalization
444
+ (converting verbs to abstract nouns — "the facilitation of onboarding", "the
445
+ optimisation of workflows") and present-participle clause stacking ("a platform for
446
+ managing, tracking, and reviewing your pipeline"). Both are addressed individually in the
447
+ plain-language section of this document. They are named here as register signals too: in
448
+ isolation each is acceptable; clustered in a hero or feature section they can obscure actor,
449
+ action, and consequence. Test whether a direct verb or concrete noun carries the same fact
450
+ more clearly in the chosen register.
451
+
452
+ ### Deterministic rule: declined
453
+
454
+ The self-introduction pattern is regex-describable:
455
+ `\b\w+ is an? (platform|tool|system|solution|app|service) that (helps?|allows?|enables?|lets?)\b`.
456
+ It is not a safe linter rule. Product comparison tables, developer documentation, feature
457
+ detail sections, and UI tooltip copy all use constructions that match this pattern
458
+ legitimately. Without reliable hero-node detection, the rule would false-positive on too
459
+ much legitimate writing to be trusted. It belongs on the hand's pre-handoff review pass,
460
+ in the same category as the not-X-but-Y construction documented above under Korean copy.
461
+
462
+ ---
463
+
464
+ ## Static copy and live dialogue have different situations
465
+
466
+ OMD's voice system covers static product writing and conversational replies without
467
+ collapsing them into one register. A page has no shared turn history: its headline, body,
468
+ state, and action must stand on their own. A live reply has a speaker, listener, prior turn,
469
+ and immediate purpose; it should use established context instead of repeating the request or
470
+ narrating the answer before answering. Acknowledgement belongs in dialogue when it repairs a
471
+ relationship, confirms a consequential instruction, or responds to an observed event. It is
472
+ not a generic opening.
473
+
474
+ The dialogue-system research below concerns timing, overlap, and assistant evaluation. Those
475
+ mechanisms do not transfer to static page copy. The broader requirement that register fit the
476
+ speaker, listener, and situation applies to both surfaces.
477
+
478
+ **Text Overlap / OverlapBot** (aclanthology.org/2025.sicon-1.10): studies backchannels,
479
+ overlapping responses, and turn-taking timing in real-time text chatbots. The paper
480
+ reports that OverlapBot produces 130% more chatbot turns than a standard system through
481
+ behaviors like backchannel signals and proactive interruption. Backchannels, overlap
482
+ timing, and turn interruption are properties of live dialogue — a landing page does not
483
+ respond, does not take turns, and has no equivalent to "음" or "I see" in a hero section.
484
+ Applying these findings to static copy would be a category error, not humanisation.
485
+
486
+ **DialogBench** (aclanthology.org/2024.naacl-long.341): a benchmark for evaluating LLMs
487
+ as conversational dialogue systems across 12 tasks. Its findings about emotional
488
+ perception and everyday-life knowledge quality apply to chatbot response evaluation, not
489
+ to page copy. The study's principle — that the assistant-AI positioning degrades register
490
+ naturalness — does transfer as a writing decision (documented above), but the benchmark
491
+ tasks and metrics themselves do not.
492
+
493
+ **Are Human Conversations Special?** (arxiv 2403.05045): an architectural study of how
494
+ transformer attention mechanisms differ across domains — conversation, web content, code,
495
+ mathematics. It identifies no surface-text patterns and transfers nothing to writing
496
+ decisions. It is cited here to prevent a future reader from importing it: the paper's
497
+ conclusion is about domain specialisation in attention heads, not about copy register.
498
+
499
+ ---
500
+
501
+ ## Sources
502
+
503
+ - Nielsen, J. (1997). "How Users Read on the Web." Nielsen Norman Group.
504
+ nngroup.com/articles/how-users-read-on-the-web/ — 79% scan finding; scanning as default
505
+ web reading behavior, not an aberration
506
+ - Morkes, J. & Nielsen, J. (1997). "Concise, SCANNABLE, and Objective: How to Write for
507
+ the Web." Nielsen Norman Group. nngroup.com/articles/concise-scannable-and-objective —
508
+ 58% usability gain for concise writing, 47% for scannable, 124% combined
509
+ - Nielsen, J. (2006). "F-Shaped Pattern For Reading Web Content."
510
+ nngroup.com/articles/f-shaped-pattern-reading-web-content-discovered/ — F-pattern as a
511
+ fallback behavior, not a design target
512
+ - Oppenheimer, D.M. (2006). "Consequences of Erudite Vernacular Utilized Irrespective of
513
+ Necessity: Problems with using long words needlessly." *Applied Cognitive Psychology*,
514
+ 20(2), 139–156. doi:10.1002/acp.1178 — plain language increases perceived intelligence
515
+ via processing fluency; complexity reduces it
516
+ - Feature-based detection of AI-generated text (Springer, *AI and Ethics*, 2025) — human
517
+ writing has greater sentence-length variance and standard deviation than model-generated
518
+ text; confirmed across academic, journalistic, and creative domains
519
+ - PMC study on academic science writing (pmc.ncbi.nlm.nih.gov/articles/PMC10328544/) —
520
+ sentence-level diversity in length and paragraph complexity as primary detection signals;
521
+ over 99% accuracy using stylometric features alone
522
+ - arXiv 2408.04647, "Distinguishing Chatbot from Human" — GPT sentences longer on average;
523
+ human writing has wider range and higher variance across sentence lengths
524
+ - Podmajersky, T. (2019). *Strategic Writing for UX.* O'Reilly Media. — voice chart as
525
+ instrument connecting product principles to copy decisions; voice applied like a spice:
526
+ too little is flavorless, too much inedible
527
+ - Mailchimp Content Style Guide (styleguide.mailchimp.com) — "plainspoken" as the core
528
+ voice dimension: strip hyperbolic language, upsells, and over-promises; clarity above
529
+ entertainment; active voice, positive language, plain English
530
+ - 37signals, "The 37signals Guide to Internal Communication" (37signals.com/how-we-
531
+ communicate) — "If your words can be perceived in different ways, they'll be understood
532
+ in the way which does the most harm"; plain writing reduces interpretive surface
533
+ - Wiebe, J. / Copyhackers, "How to do rapid-fire review mining"
534
+ (copyhackers.com/how-to-do-rapid-fire-review-mining/) — voice-of-customer method:
535
+ mine real user language from reviews and forums; the customer names the value better
536
+ than the copywriter
537
+ - Toss Tech. (2022). "토스의 8가지 라이팅 원칙들."
538
+ toss.tech/article/8-writing-principles-of-toss — eight principles built from A/B test
539
+ data: Predictable hint, Weed cutting, Remove empty sentences, Focus on key message, Easy
540
+ to speak (avoid 한자어 and 문어체), Suggest over force, Universal words, Find hidden emotion
541
+ - Toss Developer Center, UX Writing Guide
542
+ (developers-apps-in-toss.toss.im/design/ux-writing.html) — 해요체 as the product-wide
543
+ standard; active voice preference; one message per sentence; native Korean over Sino-Korean
544
+ - 배민 UX Writing interview (bcut.baemin.com/6287/) — first UX writer mandate: clear
545
+ communication and consistency of voice; register as a designed commitment, not a default
546
+ - Qian et al. (2025). "Enhancing Human-Like Responses in Large Language Models."
547
+ arxiv.org/abs/2501.05032 — DPO fine-tuning removes robotic formal register; self-intro
548
+ disclaimers, impersonal deflection, and encyclopedic structure identified as primary tells;
549
+ 79–90% preference for natural responses with no benchmark degradation
550
+ - Jiang et al. (2025). "How Human-Like Are Large Language Models? A Register-Aware
551
+ Linguistic Evaluation Framework." arxiv.org/abs/2605.23651 — LLMs over-produce
552
+ nominalisations, longer words, attributive adjectives, and present-participle constructions
553
+ across all registers; human instructive text is more persuasive and more lexically variable
554
+ - Ou et al. (2024). "DialogBench: Evaluating LLMs as Human-Like Dialogue Systems."
555
+ aclanthology.org/2024.naacl-long.341 — DIALOGUE-ONLY: benchmark for conversational
556
+ agents; finding that assistant-AI positioning weakens emotional naturalness transfers as
557
+ a writing principle (choose register deliberately); evaluation tasks do not transfer
558
+ - Liu et al. (2024). "Are Human Conversations Special? A Large Language Model Perspective."
559
+ arxiv.org/abs/2403.05045 — EXCLUDED: architectural study of attention mechanisms by
560
+ domain; no surface-text patterns; does not apply to copy writing decisions
561
+ - Lala et al. (2025). "Text Overlap: An LLM with Human-like Conversational Behaviors."
562
+ aclanthology.org/2025.sicon-1.10 — EXCLUDED: backchannels, overlap, and turn-taking in
563
+ real-time text chatbots; findings are dialogue-system-specific and do not apply to static
564
+ page copy
565
+
566
+ ---
567
+
568
+ ## Official evidence map and layer ownership
569
+
570
+ - **Toss writing principles** — https://toss.tech/article/21022 — writer: one key message,
571
+ remove repeated/empty lines, make the next screen predictable, use one spoken breath,
572
+ preserve user choice. Eye: read aloud and test CTA prediction.
573
+ - **Toss marketing writing** — https://toss.tech/article/Marketing_Writing — writer: connect
574
+ the audience's present concern to a concrete next action; do not turn a click-rate tactic
575
+ into an unsupported product claim.
576
+ - **Apple Writing HIG** — https://developer.apple.com/design/human-interface-guidelines/writing
577
+ — writer: clear, concise, useful labels in the platform's voice. Hand: place text where it
578
+ explains the affected control or state.
579
+ - **Microsoft UI text guide** — https://learn.microsoft.com/en-us/windows-server/manage/windows-admin-center/extend/guides/ui-text-style-guide
580
+ — writer: consistent terminology, direct action labels, sentence-style capitalization.
581
+ - **W3C Writing for Web Accessibility** — https://www.w3.org/WAI/tips/writing/ — writer:
582
+ descriptive headings/link text and plain language. Hand: expose the same meaning to
583
+ assistive technology.
584
+
585
+ Ownership is deliberate. `omd-writer` establishes facts, audience language, voice, and
586
+ surface copy in `.omd/copy-deck.md`. Copy-editor eye judges fact fidelity, scan, repetition,
587
+ CTA prediction, register, emotion, and recovery in context. `omd copy --check` verifies only
588
+ explicit structure, state applicability, exact unresolved sentinels, and fact-ID links.
589
+
590
+ Screenshot phrases and common connectives are prompt/eval observations, never global lint:
591
+ legitimate brands and sentences use them. AI detectors, perplexity thresholds, and sentence-
592
+ length distributions are forbidden as shipping gates: domain, language, accessibility copy,
593
+ and short UI labels create false positives, and a statistical signal cannot establish
594
+ authorship or copy quality. Use those ideas only to prompt a contextual human/eye review;
595
+ never reject a deck because a detector score or distribution looks machine-like.