Voice, icons & motion

Voice

Funny. Sarcastic. Quietly grumpy. Friendly underneath all of that. The voice you'd use telling a friend why their staging environment is on fire — not the voice a product manager dictates into a Notion doc.

This is a personal portfolio system. The writing is half the reason anyone would pick it over the seventeenth identical shadcn template on the internet. Use it.

The five rules

1. Aim the sarcasm at the situation, not the user. Roast the spinner. Roast distributed systems. Roast whoever named their project Untitled-3. Don't roast the human reading the screen — they chose your product, that's already a kindness.
2. Clarity wins, always. A joke that hides what happened or what to do next is a bug. Write the working sentence first, then see if the leftover syllables want comedy.
3. No apologies. No “Sorry,” no “We're working hard to fix this,” no exclamation points. Apology copy reads as insecure; this product isn't.
4. Save it for the loud moments. Empty states, errors, confirmations, the hero, the 404, the splash text. The settings panel can stay boring — should, even. If every label is a punchline, none of them are.
5. No dad humor. No “Whoopsie,” no Houston references, no “loading awesomeness,” no pop culture that ages in a calendar year. Smart-funny, not desperate-funny. If a copywriter at a SaaS company would high-five it, delete it.

What it sounds like

Casing

• Sentence case for buttons, headings, labels, menu items, table headers — basically everything except product names. “Save changes,” not “Save Changes.”
• Title Case only for proper nouns (product names, feature names that function as products).
• No ALL CAPS outside of brand wordmarks and unit labels (KB, MB, GMT). Phosphor weight + tracking carries the same emphasis without screaming.

Button labels

• Verb-led, terse. “Save,” “Cancel,” “Add member,” “Invite teammate.” Not “Submit,” “OK,” “Members,” “Click here.”
• Object after verb when ambiguous. “Add” alone is fine in a member list (the object is implied); “Add” alone next to four other “Add” buttons is not — make it “Add member.”
• Destructive uses the verb directly. “Delete project,” not “Confirm.” The user should be able to read the button alone and know what will happen.

Error messages

Two parts, in this order: what happened + how to fix it. The voice is the third ingredient — slip it in after those two are clear, never instead of them.

Empty states

Two parts: what's missing + concrete next action. Empty states are prime real estate for the voice — the user has nothing to read, so they'll actually read this.

• “No projects yet. The first one's always the hardest.” → button: “Create project”
• “No results for ‘synergy’. Try fewer adjectives.” → button: “Clear filters”
• “Inbox zero. You've achieved what most can only dream of.” → (maybe no button — let them have the moment)
• “No team members. It's lonely at the top.” → button: “Invite teammate”

Confirmation & success

Brief, past tense, optional shrug. Toasts prefer ≤ 8 words. Don't high-five the user — it's saving a form, not curing cancer.

• “Saved. You're welcome.”
• “Created. Try not to delete it immediately.”
• “Invite sent. They'll either thank you or block you.”
• “Done. That was easy.”
• “Published. Live and irreversible.”

Loading states

• Skeleton for content that has a known shape (a list of cards, a table row). Always preferred over spinners for content.
• Spinneronly for ≤ 2s actions (button submission, modal close after save). If it's longer, swap to skeleton or progress.
• Progress when you can quote duration or percentage (uploads, imports, multi-step forms).

Numbers, dates, units

• Numbers: thousand-separator on counts ≥ 10,000 (1,234 not 1234 when shown as a count; 1234 is fine for IDs).
• Dates: relative for < 7 days (“2h ago”), absolute after.
• Times: 24h in dashboards / dev tooling, 12h in consumer products. Pick once per product.
• Units: space before (3 KB), no plural form (1 KB, not 1KBs).

Kaotypr uses Phosphor as its icon set. Sizing is tokenized via --size-icon-*; weight is a stylistic decision with rules.

Phosphor weights

• Regular (default) — most icons in your UI. Toolbar, sidebar, inline icons.
• Duotone— active / current / emphasized states. Kaotypr uses it on the active sidebar item, current step in a wizard, and in headlines (e.g. the foundation page's tier-card icons).
• Fill — status icons (always paired with a status surface), and affordances that need to read at a glance from far away (close buttons in modals, drag handles).
• Bold / Light / Thin — avoid. They break the visual rhythm with the rest of the system.

Sizing

• size-(--size-icon-sm) — inline with body text, list rows, sidebar nav
• size-(--size-icon-md) — toolbar buttons, table actions, badges
• size-(--size-icon-lg) — empty-state illustration, page-level affordance

Icon + label vs icon-only

Server-rendered icons

For server components and SEO-critical surfaces, import from @phosphor-icons/react/ssr— these are tree-shakeable and don't bring the client runtime. Use @phosphor-icons/react only when you actually need a client component (e.g. animated weight switching).