1# STYLE.md
  2
  3Editorial brief for impeccable.design. Read this before writing or editing user-facing copy: the homepage, sub-pages, command editorials, tutorials, and READMEs.
  4
  5The bar: **for every paragraph, point to the sentence that makes it specifically yours.** If you can't, the paragraph is AI by default, even if a human typed it.
  6
  7## Principles
  8
  91. **Open with the reader's wrong belief, your strongest claim, or the example.** No "in this guide", no "let's dive in".
 102. **Take a position someone could disagree with.** If the paragraph could be inverted without changing meaning, it has no position. Sign your stance.
 113. **Name names. Use numbers.** Real competitors, real customer names, real version numbers, real file paths, real benchmarks. Cut "lightweight"; write "54 KB".
 124. **Verbs lead. Nouns follow.** Imperative is fine. Active voice. Cut nominalizations ("the implementation of" → "implementing").
 135. **Vary sentence length on purpose.** Long, long, short. Smooth uniform rhythm is the deepest AI tell.
 146. **Prose carries the load; structure supports it.** Bullets are for parallel options. Paragraphs are for argument. Don't bullet what would be tighter as a sentence.
 157. **Plain words. Technical terms only when something specifically rests on them.** Mixing levels lets the technical terms hit harder.
 168. **Allow ungrammatical fragments for rhythm.** Five words. Confidence signal.
 179. **Respect the reader's competence.** No "developers should consider"; just "you might not need an effect".
 1810. **Read it aloud. Fix anything you stumble over.**
 1911. **Concrete over comprehensive.** Coverage is an AI obsession. Trade coverage for momentum. Leave things out.
 2012. **Close by handing off the next move.** Don't summarize. End on the strongest sentence, give a directive ("Now do this"), or just stop.
 21
 22## Denylist
 23
 24The build's `validateProse` step (in `scripts/build.js`) fails the build on these. The list is the editorial brief, enforced. Add a rule here when you ban a new pattern; remove a rule when the term has earned a real meaning here. **Do not silently allowlist** by working around the regex.
 25
 26### Stolen-engineer diction
 27Engineering words that became AI flavor once they leaked into training data around late 2024.
 28
 29| Banned | Why | Use instead |
 30|---|---|---|
 31| `load-bearing` | Almost always vague. The literal sense is rare. | Name the specific thing it does. "The decision that shapes the rest", "carries the brand", "matters specifically". |
 32| `highest-leverage` | Vague claim of impact. | Say what specifically pays off. "The change that moves the design most". |
 33| `biggest unlock` | Marketing-speak. | Describe the actual change. |
 34
 35### Internal jargon leaking out
 36Words that work in a research notebook and fail in user copy.
 37
 38| Banned | Why | Use instead |
 39|---|---|---|
 40| `reflex defaults` | Eval-team jargon. | "Instincts", "first guesses", "default reaches". |
 41| `collapses into monoculture` | Eval-paper voice. | Describe what specifically went wrong (e.g. "every model picked the same three fonts"). |
 42| `data-driven` | Empty marketing adjective. | Cite the data. "Validated against 15 briefs across two models". |
 43
 44### Marketing voice
 45Adjectives and verbs that gesture at quality without doing the work.
 46
 47| Banned | Why | Use instead |
 48|---|---|---|
 49| `seamless`, `seamlessly` | Hollow positive. | Say what specifically works without friction. |
 50| `robust`, `robustness` | Hollow positive. | Cite the failure mode handled. |
 51| `elevate`, `elevates` | Marketing verb. | Use the specific verb (improve, raise, sharpen). |
 52| `empower`, `empowers` | Marketing verb. | "Let you", "make possible". |
 53| `underscore`, `underscores` | AI tell. | "Show", "make clear". |
 54| `pivotal` | Hollow positive. | "Central", "key", or describe the role. |
 55| `tapestry` | AI scenery noun. | Cut. |
 56
 57### Verbs
 58| Banned | Why | Use instead |
 59|---|---|---|
 60| `delve`, `delves`, `delved`, `delving` | The most-flagged AI tell of all. | "Look at", "explore", or just delete the throat-clearing verb. |
 61
 62### Throat-clearing
 63Sentences that delay the point. Cut them; almost nothing of value is lost.
 64
 65| Banned | Why | Use instead |
 66|---|---|---|
 67| `in today's …` | Generic opener. | Start at the actual point. |
 68| `gone are the days` | Cliché opener. | Make the point directly. |
 69| `whether you're …` | Audience-pandering; addresses no one. | Pick one reader. Write to them. |
 70| `let's dive in` | Throat-clearing. | Just start. |
 71
 72### Closers
 73| Banned | Why | Use instead |
 74|---|---|---|
 75| `in summary`, `in conclusion` | Restates what was just said. | End on the strongest sentence. Trust the reader. |
 76
 77### Transitions
 78| Banned | Why | Use instead |
 79|---|---|---|
 80| `moreover`, `furthermore` | Metronome transition crutch. | Drop, or use "also", or restructure. |
 81
 82### Punctuation
 83| Banned | Why | Use instead |
 84|---|---|---|
 85| Em dash `—` (and HTML entities `—`, `—`, `—`) | Decision-avoidance: writer didn't pick a relationship between the clauses. | Comma, colon, semicolon, period, parentheses. Pick the relationship. |
 86| ` -- ` (double hyphen as em-dash substitute) | Worse than the em dash. Signals failed cleanup. | Real punctuation. |
 87
 88## Patterns the validator can't catch
 89
 90The above are the easy wins. The deeper issues require human judgment on every paragraph.
 91
 92- **Negation pivot.** "It's not just X, it's Y." "Less about X, more about Y." This is now a stronger AI tell than any vocabulary item. Use sparingly. Most instances should be replaced with a direct positive claim.
 93- **Triadic everything.** Every list exactly three items. Every adjective in groups of three ("fast, simple, and powerful"). Vary count: use 2 or 4. Use 1.
 94- **The five-paragraph essay shape.** Intro → 3 sections → conclusion, on every page. Mix it up. Lead with the example. Skip the conclusion. Let some sections be one sentence.
 95- **Uniform paragraph length.** Insert a 4-word sentence. Insert a one-line paragraph.
 96- **Synthetic balance.** Pros and cons of equal length when one is clearly right. Write the recommendation; note real exceptions briefly.
 97- **Hollow confidence.** "Powerful" without numbers. Replace with a concrete fact.
 98- **Hedging stacks.** "It might potentially be useful to consider..." Each hedge is fine; stacked, they sound trained.
 99- **Interchangeable copy.** Swap "Impeccable" for a competitor name. If nothing becomes false, the copy is generic.
100
101## When in doubt
102
103Read the paragraph aloud. If you stumble, rewrite. If a sentence describes nothing specific to this product, cut it.