STYLE.md

STYLE.md

Editorial brief for impeccable.design. Read this before writing or editing user-facing copy: the homepage, sub-pages, command editorials, tutorials, and READMEs.

The 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.

Principles

  1. Open with the reader's wrong belief, your strongest claim, or the example. No "in this guide", no "let's dive in".
  2. Take a position someone could disagree with. If the paragraph could be inverted without changing meaning, it has no position. Sign your stance.
  3. Name names. Use numbers. Real competitors, real customer names, real version numbers, real file paths, real benchmarks. Cut "lightweight"; write "54 KB".
  4. Verbs lead. Nouns follow. Imperative is fine. Active voice. Cut nominalizations ("the implementation of" → "implementing").
  5. Vary sentence length on purpose. Long, long, short. Smooth uniform rhythm is the deepest AI tell.
  6. 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.
  7. Plain words. Technical terms only when something specifically rests on them. Mixing levels lets the technical terms hit harder.
  8. Allow ungrammatical fragments for rhythm. Five words. Confidence signal.
  9. Respect the reader's competence. No "developers should consider"; just "you might not need an effect".
  10. Read it aloud. Fix anything you stumble over.
  11. Concrete over comprehensive. Coverage is an AI obsession. Trade coverage for momentum. Leave things out.
  12. Close by handing off the next move. Don't summarize. End on the strongest sentence, give a directive ("Now do this"), or just stop.

Denylist

The 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.

Stolen-engineer diction

Engineering words that became AI flavor once they leaked into training data around late 2024.

Banned Why Use instead
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".
highest-leverage Vague claim of impact. Say what specifically pays off. "The change that moves the design most".
biggest unlock Marketing-speak. Describe the actual change.

Internal jargon leaking out

Words that work in a research notebook and fail in user copy.

Banned Why Use instead
reflex defaults Eval-team jargon. "Instincts", "first guesses", "default reaches".
collapses into monoculture Eval-paper voice. Describe what specifically went wrong (e.g. "every model picked the same three fonts").
data-driven Empty marketing adjective. Cite the data. "Validated against 15 briefs across two models".

Marketing voice

Adjectives and verbs that gesture at quality without doing the work.

Banned Why Use instead
seamless, seamlessly Hollow positive. Say what specifically works without friction.
robust, robustness Hollow positive. Cite the failure mode handled.
elevate, elevates Marketing verb. Use the specific verb (improve, raise, sharpen).
empower, empowers Marketing verb. "Let you", "make possible".
underscore, underscores AI tell. "Show", "make clear".
pivotal Hollow positive. "Central", "key", or describe the role.
tapestry AI scenery noun. Cut.

Verbs

Banned Why Use instead
delve, delves, delved, delving The most-flagged AI tell of all. "Look at", "explore", or just delete the throat-clearing verb.

Throat-clearing

Sentences that delay the point. Cut them; almost nothing of value is lost.

Banned Why Use instead
in today's … Generic opener. Start at the actual point.
gone are the days Cliché opener. Make the point directly.
whether you're … Audience-pandering; addresses no one. Pick one reader. Write to them.
let's dive in Throat-clearing. Just start.

Closers

Banned Why Use instead
in summary, in conclusion Restates what was just said. End on the strongest sentence. Trust the reader.

Transitions

Banned Why Use instead
moreover, furthermore Metronome transition crutch. Drop, or use "also", or restructure.

Punctuation

Banned Why Use instead
Em dash — (and HTML entities —, —, —) Decision-avoidance: writer didn't pick a relationship between the clauses. Comma, colon, semicolon, period, parentheses. Pick the relationship.
-- (double hyphen as em-dash substitute) Worse than the em dash. Signals failed cleanup. Real punctuation.

Patterns the validator can't catch

The above are the easy wins. The deeper issues require human judgment on every paragraph.

  • 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.
  • 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.
  • 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.
  • Uniform paragraph length. Insert a 4-word sentence. Insert a one-line paragraph.
  • Synthetic balance. Pros and cons of equal length when one is clearly right. Write the recommendation; note real exceptions briefly.
  • Hollow confidence. "Powerful" without numbers. Replace with a concrete fact.
  • Hedging stacks. "It might potentially be useful to consider..." Each hedge is fine; stacked, they sound trained.
  • Interchangeable copy. Swap "Impeccable" for a competitor name. If nothing becomes false, the copy is generic.

When in doubt

Read the paragraph aloud. If you stumble, rewrite. If a sentence describes nothing specific to this product, cut it.