DevStackBox Writing Guidelines

Product-wide rules for UI, installer, documentation, release notes, and changelog.

See also: Terminology, UI Guidelines.

Voice

DevStackBox communicates like a professional developer tool.

Writing should be:

• Clear
• Direct
• Calm
• Helpful
• Concise

Avoid:

• Marketing exaggeration
• Corporate jargon
• AI-style wording (Executing cleanup task..., Beginning service termination...)
• Humor inside system messages
• Excessive punctuation

Target tone: VS Code, Windows Terminal, JetBrains, Visual Studio.

Don't apologize

State facts. Do not apologize in errors or system messages.

Terminology

Use one vocabulary. The glossary below covers preferred terms.

Capitalization

Buttons

Always verbs:

Start | Stop | Restart | Install | Update | Refresh | Browse | Open | Save | Restore | Delete | Cancel

Never: Do Start, Run Service, Execute, Proceed.

Button variants: see Button variants below.

Confirmation dialogs

Title:    Delete Database
Body:     This action permanently deletes the database.
Buttons:  Delete | Cancel

Not: Are you sure? as the title.

Toasts

Past tense, short, no "successfully":

Apache started.
Configuration saved.
Backup completed.

Errors

Three parts - always actionable:

1. What failed
2. Why
3. What to do

Example:

Unable to start Apache.

Port 80 is already in use.

Stop the application using port 80 or change the Apache port.

Not: Operation failed.

Empty states

No databases found.

Create a database to get started.

Not: Nothing here.

Status vocabulary

Use one set everywhere:

Running | Stopped | Starting | Stopping | Installing | Updating | Downloading | Ready | Completed | Failed

Do not mix: Done, Finished, Complete, Succeeded.

Prefer structured layout:

Apache
Running

or Status: Running - not Apache -> Running.

Numbers

5 databases
1 database

Never: 5 Database(s).

Time

Just now
2 minutes ago
1 hour ago
Yesterday

Do not mix: a moment ago, secs ago, few seconds ago.

Punctuation and icons

• In-progress: three dots - Checking for Updates...
• Completed: period - Apache stopped.
• No emoji in product UI or project docs
• No Unicode decorative symbols in text - use Lucide icons in the app UI
• Do not replace selection indicators with the word Selected

Installer and uninstaller progress log

Human, Visual Studio-style. Not verbose.

Stopping Apache...
Apache stopped.

Stopping MySQL...
MySQL stopped.

Removing application files...
Removing shortcuts...
Removing registry entries...
Removing user data...

Completed.

Branded component names in logs: Apache, MySQL, PHP, phpMyAdmin.

Scope

These rules apply to: app UI, README, installer/uninstaller, docs, release notes, and changelog.

DevStackBox Terminology

Glossary for consistent product language. When in doubt, use the Preferred term.

Install location: C:\devstackbox

Application data: %LOCALAPPDATA%\devstackbox

DevStackBox UI Guidelines

Stub - expand as the design system matures. Writing rules are in the first section of this page.

Button variants

Confirmation dialogs

• Short title (noun phrase)
• One or two sentence body explaining consequence
• Confirm button matches action verb (Delete, not OK)
• Cancel always available

Icons

See Icon Guidelines below.

DevStackBox Color Guidelines

Stub - expand later.

Use Tailwind CSS and shadcn/ui theme tokens. Support light and dark mode.

Destructive actions use the destructive button variant and semantic error colors from the theme - do not hardcode one-off reds in feature code.

DevStackBox Icon Guidelines

Stub - expand later.

Library

Use Lucide icons only (via lucide-react).

Selection indicators

Use the Lucide Check icon for selected items (language switcher, lists). Do not use Unicode checkmarks or the text Selected.

Status

Use Loader2 with spin animation for in-progress states.