visant-copy

Visant Copy

Two things live here: how Visant copy sounds (valid in any repo) and how it is operated, which depends on where the text lives. The voice below is for Brazilian Portuguese; for English copy read [english.md](references/english.md). The linter runs a PT and an English rule set on every input.

• The repo uses Visant's pipeline (copy*.json at the root and

copy:build/copy:check scripts in package.json): the JSON is the SSoT and the HTML is a generated view, so never edit text directly in the .html. See "If the repo uses Visant's pipeline".

• Any other repo (copy inside the component, .md, exported CMS): the

component is the SSoT, and the risk is echo, the same sentence in four files.

Find out which one before touching text:

ls copy*.json 2>/dev/null; grep -nE '"copy:(lint|build|check)"' package.json

Either way, never write Visant copy without going through the prohibitions below. Asked to audit a page? A clean linter says little: follow references/audit.md.

Pick the register first

The voice is one; who is speaking changes. Decide before the first sentence.

Signed is where the voice comes from, so read the signed register before writing anything longer than a section, in any register.

Rule zero: propose, never apply

Only the tic fixes the linter points out go into the file. A headline, lead or sentence that passes clean stays untouched, even if you think it sounds flat.

Style improvements go as a proposal table in the report (key, before, after), and the user picks row by row. Rewriting what was already good burns trust and makes the user review the reviewer.

An audit changes nothing yet. Asked to audit or review, deliver the table, tics included, and ask which rows to apply.

The exception is an explicit request. "Essa copy tá confusa, tem que ser na pegada X" is a work order, not an invitation to debate: apply it, show the before/after table, and leave one or two ONE-line alternatives at the end, so a swap costs one Edit and not a new round. Returning only options when the user already gave the direction pushes the work back to them.

The prohibitions

Absolute. They apply to headline, body, CTA, FAQ, email, caption, alt text, error message, meta description. No "but here it worked" exception. The only one is rule 3, and context decides it: a real reversal is not the AI tic.

1. Dash (— or –) never. Period, comma, colon or parentheses.
2. Separator dot (`·`, alt+7) never. Not in metadata lists, not in a CTA with

a price, not in a phase label, not on the social card. In a list it becomes period and comma ("34 páginas. 9 etapas, 1 case inteiro"), in a label a colon ("Fase 1: A Estratégia"), in a CTA a preposition ("Quero o e-book por R$ 47").

1. "Não é X, é Y" never. Not split in two sentences ("Não é uma lista. É uma

cascata."). Not the sentence that defines by negation ("Não é slogan.").

1. "É sobre X" never. It asserts nothing. Swap it for the verb of what the

thing does.

1. "Não é apenas X, é X e Y" never. Nor "mais que apenas", "menos X e mais

Y", "não se trata de".

1. Negation dangling at the end never. "Feito pra ler, não pra arquivar."

Delete the tail and the sentence gets stronger.

1. Emoji never. Semicolon never. (©, ®, ™ are trademarks and stay.)
2. Guru openings never. "Imagine que", "E se eu te dissesse", "Prepare-se

pra", "Chegou a hora de". Start with the fact or the scene.

1. Cliché urgency never. "Últimas vagas", "corre que acaba", "por tempo

limitado". Scarcity must be countable: say the number ("este lote tem 30 vagas", "a cota sobe a cada compra").

1. Credibility seal at most once per page. "real", "de verdade", "na

prática", "de fato", "genuíno", "autêntico", "honesto". One passes. With two, the reader counts and posts a screenshot ("trajetória real, projeto real, técnica real, processo real"). An adjective does not prove; numbers and scenes do. Sete anos de projeto real → Sete anos entregando marca.

The rule that solves 3 to 6: cut the negative half. The sentence that remains is almost always the right one. If the contrast really is the argument, show the consequence instead of negating: instead of "não é falta de talento, é falta de ordem", write "Talento você já tem. O que falta é ordem."

The linter

Running it before delivering copy is mandatory. Plain node, no dependencies, runs in any repo:

L=<skill-dir>/scripts/copy-lint.mjs
node $L copy.json                       # copy JSON
node $L hero.tsx page.tsx og.tsx        # components, passed TOGETHER
node $L README.md docs/landing.md       # markdown or plain text
npm run copy:lint                       # if the repo uses Visant's pipeline

Folders are walked, generated files skipped. Inputs, flags and rule ids: references/linter.md.

Exit 1 with the key, the excerpt and the fix. Two warnings come outside the exit code, because good copy cannot fail on a detail:

• length per line type (headline 60, CTA 28, lead 180, body 280, SEO title

60, meta description 160), inferred from the key suffix, so .json only; it flags the headline that breaks into three lines on mobile;

• echo, when the same sentence lives in two of the files passed in the same

call. That is why you pass the files together, never one at a time.

In code files comments are not linted on purpose: a JSDoc is not copy.

Repetition budget is per PIECE, and the file is not always the piece

credibility-seal (limit 1, PT and EN words share it) counts per piece: in JSON the first key segment (onboarding.*), in a component the file. Money (R$ 47) is not a seal; the rest is semantic, so confirm at file:line. Why.

The voice

Pattern taken from Visant's e-book landing and from what the studio publishes under its own name. In order of importance:

1. Spoken Brazilian, by ear. "para" and "pra" both live here: written lines

lean "para", spoken beats take "pra", "tá", "tô". Never swap one for the other mechanically. No "cê", "mano", "tá ligado". Short imperative: "Lê e julga".

1. Short sentence after short sentence. Average 12 words. **A verbless

fragment is a device**, always as a punch after the long sentence: "…e a marca se comporta de outro jeito três meses depois. Toda vez."

1. Scene instead of adjective. Never "inconsistência de marca". Write what is

seen: "Um post fala uma coisa, o atendimento fala outra, o site parece de outra empresa."

1. Blame starts with the author, and only if it happened. Never invent a

scene, memory or confession: ask, or mark the place. Confess before charging: "A gente começava pelo logo também. Perdeu semanas assim, até inverter a ordem." Accusing the reader directly ("você começa pelo logo porque é a parte divertida") only after the confession, if at all.

1. Raw numbers, not rounded to impress. R$450k, 160+ lives,

34 páginas, 7 dias.

1. Admit limits. "Se algo não funcionou pra gente, tá escrito que não

funcionou." It is what most separates the voice from AI text.

1. Humor by mocking the market, dry and unsignposted: "Sem aula de 40 horas

ensinando a centralizar retângulo." It targets the practice, never the person.

1. Mild swearing, at most one per page, and only where the argument hurts:

"porcaria", "cagada". Never in the CTA or the main headline.

1. Objections in the reader's voice. The FAQ is what the person thinks, in

their words: "Já faço branding há anos. Vou ver algo novo?". The answer opens by answering ("Serve.", "É."), never with "Ótima pergunta".

1. Takes a position and owns it. "Eu acho triste", then "mas não importa se

eu acho isso bom ou ruim". Grant the best counterargument before answering it.

1. The specific analogy, announced. "Um exemplo meio tosco": the Subway order

with "exatamente 12 azeitonas pretas". Detail too exact to be invented is what AI text lacks.

Line-by-line detail, vocabulary, anglicisms, money, CTA, and the before/after table: references/voice.md. Read it before writing a new piece or rewriting a whole section.

The fold names the TASK, not the state

Applies to the H1, the <title> and the social card, and it is the most expensive mistake because it passes every linter.

State copy describes the reader's world and leaves them to work out what they gain: "Você tem centenas de mockups parados no disco." It is correct, real pain, and asks for nothing. Task copy names the verb the person came to do: "Ache o mockup certo sem abrir um PSD."

The test is one question: which verb would the reader type into Google? If the headline lacks that verb, it talks about the state. And beware the wrong task: before writing, check which step really hurts (example in references/cases.md).

When the pain needs to show (and sometimes it does), it goes in the next section, opening the mechanism. On the fold you have 5 seconds, and spending all five describing the problem is wasting your turn.

The product line says what the reader gets

The line under a product or feature name, also invisible to every linter. It fails in three ways:

• Describes the mechanism from inside. Audita antes do PR is correct, and

it asks the visitor to know what a PR is and why auditing helps. Write what they walk away with: Olho de designer para o seu Claude Code.

• Lists nouns. Movimento e espera names a topic. A line has a verb or a

gain.

• Promises more than the thing does. Before writing "sozinho", "tudo",

"treinado" or "em minutos", open what the product really does. A claim the demo beside it contradicts costs more than a flat line.

Visant's own brand terms: glossary. In client copy, the glossary is the client's.

If the repo uses Visant's pipeline (copy.json)

Copy lives in the JSON. HTML and Markdown are generated views. Editing text in the .html is always wrong: the next build overwrites it and the check breaks the deploy. Flow: edit the JSON, npm run copy:lint, npm run copy:build, commit json + html + md together (copy:check in the gate catches drift). SEO (meta.title, meta.description, meta.og_*) lives in the JSON too, injected via data-copy-attr="content".

Full mechanics (new key, new page, data-copy-attr, \n becoming <br>, orphan key error, setting it up in a new repo): references/pipeline.md.

When there is no copy.json (any other repo)

The component is the SSoT. Do not set up a copy.json in the middle of a text task. The risk changes shape: the same sentence lives in three or four places, so after changing the headline, hunt the echoes with rg. The social card and the <title> get forgotten most. Where they hide, and why the <title> keeps the search noun: references/pipeline.md.

Work order on "review/write the copy"

1. Read the page's whole JSON (or the whole component) before touching any key.

Including comments: they hold the WHY of the current line, and copy that contradicts the decision documented there is rework.

1. Run copy-lint to get the map of tics.
2. Apply only the tic fixes, and the rewrite the user asked for with a

direction. Everything else becomes a proposal in a table.

1. Check every number against the source of truth (server-side price, client

count, member count). The skill does not store those values on purpose: they age. When in doubt, ask before publishing.

1. Hunt the echo of the old sentence (rg, or the linter's echo warning with

the files passed together) and update the social card, <title>, description and alt.

1. If you touched a code comment, update what it explains: a comment defending

the old copy lies to the next dev.

1. Run copy-lint again. With Visant's pipeline, also copy:build and

copy:check. In a React/TS repo, tsc --noEmit.

1. Report the before/after of the changed lines. The user approves text by

reading text, never by reading a summary of the text.

Neighbors

• Feedback: when the work is delivered, ask once per session, in one line, what helped and what was missing; it goes to https://ui.visantlabs.com/skills#feedback
• [[visant-design]]: the layout around the words
• [[visant-killer]]: a screen that looks AI-made; this skill handles text that reads AI-made
• [[visant-headlines]] (Visant internal): a client brand's voice; this skill is Visant's voice
• [[visant-new-site]] (Visant internal): the copy of a whole client site
• [[revenue-centric-design]]: the lever behind the message; this skill writes the sentence