Brainforge Knowledge

slack-ux-guidelines

5 min read

Slack UX Guidelines for Brainforge Apps

Purpose: Apply Slack’s official Block Kit and messaging best practices to our Slack flows (Linear dry-run, Brainforge Assistant, notifications). Use this when designing or changing messages, threads, and interactive blocks.

Sources: Slack Block Kit and messaging docs; Perplexity: Best UX inspirations for Slack bots (Block Kit examples, Brilliant Bots, approval cards, progressive disclosure); Slack: Designing with Block Kit, Message threading, AI-enabled apps best practices.

1. Threading

  • Parent message = short and scannable. One line (or a few) that answers: what happened, which entity (e.g. which meeting), when, and one sentence of context. Details live in the thread.
  • Always post details as threaded replies using thread_ts (the parent message’s ts). Never post the “detail” message as a separate top-level message in the channel.
  • First message must identify the subject: e.g. meeting title, when it occurred, and a one-sentence summary so people know what the thread is about without opening it.

Applied in: Linear dry-run (parent: meeting title + when + one-liner + “View meeting” + “See thread”; thread: proposed tickets and Approve/Reject).

2. Content and copy

  • Clear and concise: Short sentences. Explain abbreviations. Avoid jargon, buzzwords, and idioms.
  • Avoid directional/sensory language: Don’t use “see above” or “the message below”; don’t rely on arrows or emoji to convey meaning.
  • Use context blocks for secondary info: Summaries, counts, errors, and references go in context blocks so the main content stays primary.
  • Fallback text when using blocks: Always set a text (or equivalent) for block messages so notifications and accessibility show a short, accurate summary (e.g. “Proposed Linear tickets: 2 updates, 1 create. Approve or reject in thread.”).

3. Color and accessibility

  • Don’t rely on color alone: Pair color with text/labels (e.g. “Reject” + danger style, “Approve” + primary).
  • Contrast: Prefer Slack’s default styles; test in both light and dark themes if using custom colors.
  • Emoji: Use sparingly; prefer end of sentence/line. Don’t use emoji as bullet points or as the only label for a control. Pair emoji with text.

4. Interactivity

  • Sensible defaults: Minimize choices. Use primary/danger for the main yes/no (e.g. Approve / Reject); hide lesser-used actions (e.g. Reassign) in channel mode to reduce noise.
  • Outcome-focused button labels: Use short verbs that describe the result, not the input: “Approve”, “Reject”, “Save”, “View details” — not “Click here”. 1
  • One primary + one escape: Prefer one primary action and one “escape” option (e.g. Approve + Reject) rather than many equal-weight choices. Max ~3 buttons per card when possible.
  • Group actions: Use a single actions block to group related buttons and keep the message compact.
  • One level of actions: Don’t nest workflows; keep the next step obvious (e.g. approve/reject, then update the message).

5. After the interaction

  • Always confirm after a click: Every button press should result in visible feedback: update the message (e.g. show “Approved by @user”), add a checkmark, or send a brief confirmation so the user never wonders if it worked. 1
  • Clean up when possible: After a user acts (e.g. Approve/Reject), consider updating the message to a short text record of what happened instead of leaving all buttons and blocks in place. Reduces clutter when returning to the thread later.

6. Notifications and discovery

  • First message is the notification: It should be enough to decide “do I need to open this?” Include: what, which entity, when, one sentence. Link to view more (e.g. “View meeting”, “See thread”).
  • Thread reply fallback: When posting blocks in a thread, provide a descriptive fallback string for the notification so the push/notification shows something useful, not a generic “Notification from The Forge”.

7. Message layout (mental model)

A pattern that works well for approval-style and notification cards: 1

  • Top: One short sentence that explains what’s happening (e.g. “Expense request from Alex – $132.45 – ‘Client lunch’.”).
  • Middle: Relevant details in 2–4 lines or fields (or a “View details” link / progressive disclosure so the main message stays short).
  • Bottom: 1–3 buttons — primary action, secondary/escape, optionally “More options” or overflow.

Keep the main message under ~5–7 lines before actions; move heavy detail behind a button or into the thread.

8. Patterns to borrow (approvals, standups, engagement)

  • Approval cards: Context line (who, what, amount/issue) + “Approve” (primary) + “Decline” (secondary) + optional “View details”. After click, update the message to show chosen state and who acted.
  • Progressive disclosure: Short summary in the message + “Details” or “View meeting” that expands or opens thread/link instead of a wall of text.
  • Prefer buttons over slash-only: For recurring flows (approvals, check-ins), use Block Kit and buttons rather than relying only on slash commands so users can act in place. 1

9. References

TopicLink
Designing with Block Kithttps://api.slack.com/block-kit/designing
Message threadinghttps://api.slack.com/docs/message-threading
AI-enabled apps best practiceshttps://api.slack.com/docs/apps/ai-best-practices
Block Kit referencehttps://api.slack.com/reference/block-kit/blocks
Slack Design: Threadshttps://slack.design/articles/threads-in-slack-a-long-design-journey-part-2-of-2/
Brilliant Bots (Slack App Directory)https://slack.com/marketplace/category/At0EFT6813-brilliant-bots
Knock: Block Kit deep divehttps://knock.app/blog/taking-a-deep-dive-into-slack-block-kit
Magic Bell: Slack blockshttps://www.magicbell.com/blog/slack-blocks
Teampay: 5 hacks for Slackbot UIhttps://chatbotsmagazine.com/5-expert-hacks-to-improve-your-slackbot-ui-50e92b9180c5
Cloverpop: Six UX challenges for Slack appshttps://www.cloverpop.com/blog/six-ux-challenges-when-building-slack-apps-and-how-we-fixed-them

Checklist for new or updated Slack flows

  • Parent message identifies what, which (e.g. meeting), when, and one sentence of context.
  • Detail/secondary content is in a thread reply (using thread_ts).
  • Block messages have a fallback text for notifications/accessibility.
  • Buttons use outcome-focused labels (e.g. Approve, Reject, View details); primary action is obvious; max ~3 per card.
  • Meaning is not conveyed by color or emoji alone.
  • Confirm or update the message after the user clicks (e.g. show “Approved by @user” or condense to a short record).

Footnotes

  1. From “Best UX inspirations for Slack bots” (Perplexity) and related case studies. ↩ ↩2 ↩3 ↩4

Graph View

Backlinks