@camox/api-contract 0.78.0 → 0.79.0

package/src/voice.ts

@@ -0,0 +1,229 @@
+// The Voice (GLOSSARY: Voice, Voice Axis): how a website speaks, as one chosen step on each of six
+// Voice Axes. The axes, their steps in order and each step's one-line definition are fixed here,
+// the same for every project: members pick a step, writers and the Voice Check read the
+// definitions, and the API stores a step by its key.
+
+/**
+ * The Voice Axes, each with its steps in order and each step's one-line definition. The Voice is
+ * a limit, not a target, and each axis's `limit` says how: under a `ceiling`, copy may sit at any
+ * step below the chosen one, never above; in a `band`, within one step of it either way.
+ */
+export const VOICE_AXES = [
+  {
+    key: "formality",
+    limit: "band",
+    name: "Formality",
+    about: "register, grammar, vocabulary",
+    steps: [
+      {
+        key: "ceremonial",
+        name: "Ceremonial",
+        definition: "elevated, ritual register; no contractions; set phrases and honorifics.",
+      },
+      {
+        key: "formal",
+        name: "Formal",
+        definition: "correct and impersonal; no contractions or slang; complete sentences.",
+      },
+      {
+        key: "neutral",
+        name: "Neutral",
+        definition: "standard written register; contractions allowed; no slang.",
+      },
+      {
+        key: "conversational",
+        name: "Conversational",
+        definition:
+          "as spoken to a customer; contractions, short sentences, questions to the reader.",
+      },
+      {
+        key: "colloquial",
+        name: "Colloquial",
+        definition: "as spoken among friends; slang, fragments, loose grammar.",
+      },
+    ],
+  },
+  {
+    key: "humor",
+    limit: "ceiling",
+    name: "Humor",
+    about: null,
+    steps: [
+      {
+        key: "grave",
+        name: "Grave",
+        definition: "solemn and weighty; treats its subject with gravity, beyond having no jokes.",
+      },
+      { key: "earnest", name: "Earnest", definition: "sincere and straightforward; no jokes." },
+      {
+        key: "light",
+        name: "Light",
+        definition: "warm, with an occasional light touch; no set-up jokes.",
+      },
+      { key: "witty", name: "Witty", definition: "jokes, irony or playful exaggeration recur." },
+      {
+        key: "irreverent",
+        name: "Irreverent",
+        definition: "mocks conventions, the industry or itself; jokes over sincerity.",
+      },
+    ],
+  },
+  {
+    key: "claimStrength",
+    limit: "ceiling",
+    name: "Claim strength",
+    about:
+      "how strongly copy praises and promises, backed or not; calls to action count only when they push urgency",
+    steps: [
+      {
+        key: "understated",
+        name: "Understated",
+        definition: "states facts only; no praise words; qualifies claims.",
+      },
+      { key: "measured", name: "Measured", definition: "modest claims; praise words are rare." },
+      {
+        key: "confident",
+        name: "Confident",
+        definition: "states benefits plainly; few praise words, no superlatives.",
+      },
+      {
+        key: "assertive",
+        name: "Assertive",
+        definition: "praise words throughout; strong claims and comparisons.",
+      },
+      {
+        key: "bold",
+        name: "Bold",
+        definition: "superlatives, sweeping promises, urgency, exclamations.",
+      },
+    ],
+  },
+  {
+    key: "expertise",
+    limit: "ceiling",
+    name: "Expertise",
+    about: "what the reader is assumed to know",
+    steps: [
+      { key: "plain", name: "Plain", definition: "everyday words only; no terms of the trade." },
+      {
+        key: "accessible",
+        name: "Accessible",
+        definition: "terms of the trade only when explained.",
+      },
+      { key: "informed", name: "Informed", definition: "common terms of the trade, unexplained." },
+      {
+        key: "technical",
+        name: "Technical",
+        definition: "precise terms, specifications and figures for practitioners.",
+      },
+      {
+        key: "specialist",
+        name: "Specialist",
+        definition: "dense jargon and references only experts follow.",
+      },
+    ],
+  },
+  {
+    key: "density",
+    limit: "ceiling",
+    name: "Density",
+    about: "words per idea, not page length",
+    steps: [
+      {
+        key: "telegraphic",
+        name: "Telegraphic",
+        definition: "fragments and lists; articles and transitions dropped where possible.",
+      },
+      {
+        key: "concise",
+        name: "Concise",
+        definition: "one idea per short sentence; nothing restated.",
+      },
+      {
+        key: "balanced",
+        name: "Balanced",
+        definition: "each idea gets the sentence it needs, with transitions.",
+      },
+      {
+        key: "descriptive",
+        name: "Descriptive",
+        definition: "ideas get detail, qualification and imagery.",
+      },
+      {
+        key: "expansive",
+        name: "Expansive",
+        definition: "ideas developed at length, with asides and restatement.",
+      },
+    ],
+  },
+  {
+    key: "distance",
+    limit: "band",
+    name: "Distance",
+    about: "who speaks, how close",
+    steps: [
+      {
+        key: "institutional",
+        name: "Institutional",
+        definition:
+          "the organization speaks of itself by name, in the third person, and doesn't address the reader.",
+      },
+      { key: "collective", name: "Collective", definition: '"we" speak about readers in general.' },
+      { key: "direct", name: "Direct", definition: '"we" speak to "you".' },
+      {
+        key: "personal",
+        name: "Personal",
+        definition: '"we" speak to "you" one to one, sharing opinions and feelings.',
+      },
+      { key: "solo", name: "Solo", definition: 'one person speaks as "I".' },
+    ],
+  },
+] as const;
+
+/** One Voice Axis, with its steps in order. */
+export type VoiceAxis = (typeof VOICE_AXES)[number];
+export type VoiceAxisKey = VoiceAxis["key"];
+/** A step of the axis `A`. */
+export type VoiceStep<A extends VoiceAxisKey = VoiceAxisKey> = Extract<
+  VoiceAxis,
+  { key: A }
+>["steps"][number];
+/** The key of a step of the axis `A`. */
+export type VoiceStepKey<A extends VoiceAxisKey = VoiceAxisKey> = VoiceStep<A>["key"];
+
+/** A Voice: the chosen step on each axis. */
+export type Voice = { [A in VoiceAxisKey]: VoiceStepKey<A> };
+
+/** The Voice a new project starts with: no hype, no wordiness, no forced jokes. */
+export const DEFAULT_VOICE: Voice = {
+  formality: "conversational",
+  humor: "earnest",
+  claimStrength: "confident",
+  expertise: "accessible",
+  density: "concise",
+  distance: "direct",
+};
+
+/** The axis with this key. */
+export const voiceAxis = <A extends VoiceAxisKey>(key: A) =>
+  VOICE_AXES.find((axis) => axis.key === key) as Extract<VoiceAxis, { key: A }>;
+
+/** Whether `key` names a step of the axis `axis`. */
+export const isVoiceStep = <A extends VoiceAxisKey>(
+  axis: A,
+  key: string,
+): key is VoiceStepKey<A> => {
+  const steps: readonly VoiceStep[] = voiceAxis(axis).steps;
+  return steps.some((step) => step.key === key);
+};
+
+/** The step with this key on the axis `axis`. */
+export const voiceStep = <A extends VoiceAxisKey>(axis: A, key: VoiceStepKey<A>) => {
+  const steps: readonly VoiceStep[] = voiceAxis(axis).steps;
+  return steps.find((step) => step.key === key) as VoiceStep<A>;
+};
+
+/** An axis a draft moves: from Live's step to the draft's. */
+export type VoiceChange = {
+  [A in VoiceAxisKey]: { axis: A; before: VoiceStepKey<A>; after: VoiceStepKey<A> };
+}[VoiceAxisKey];