Stats
Actions
Tags
From harness-claude
Writes toggle labels, preference descriptions, and consequence previews for settings panels. Focuses on describing effects rather than controls, with accessibility considerations.
How this skill is triggered — by the user, by Claude, or both
Slash command
/harness-claude:ux-settings-preferencesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Settings and preferences copy — toggle descriptions, preference explanations, consequence previews, settings organization
Settings and preferences copy — toggle descriptions, preference explanations, consequence previews, settings organization
Describe the effect of the setting, not the setting itself. The label names the control; the description should explain what enabling or disabling it changes in the user's experience. "Email notifications" as a label is fine -- but the description should say "Get an email when someone comments on your work or assigns you a task" not "Manage your email notification preferences." Slack's notification settings say "Notify me about: Direct messages, mentions, and keywords" -- the effect is described, not the category. Figma's comment notifications say "Notify me when someone comments on a file I can edit" -- the trigger condition is explicit, not implied. A user reading only the description, without the label, should be able to understand exactly what will change in their experience if they toggle the setting.
Toggle labels use noun phrases describing what is enabled -- not the current state. A toggle labeled "Notifications: ON" is problematic because the meaning inverts when the toggle is off. The label must work in both states. Use "Email notifications" not "Enable email notifications" (the toggle conveys enabled/disabled -- the label should not duplicate it). Use "Show avatars in sidebar" not "Avatars: Visible." Apple's System Settings toggles follow this pattern universally: "Allow apps to request to track" describes the permission, not the state. The label remains accurate whether the toggle is on or off, and screen readers announce it correctly in both states without the label needing to change.
Write consequence previews for settings with significant or irreversible side effects. Users should know what will happen before they flip the toggle, not after. Settings that log out all other sessions, delete data, change visibility, or affect other users require inline consequence text placed directly beneath the toggle, visible before the user interacts. Atlassian Jira shows under the "Disable account" toggle: "This will remove this user's access to all projects and revoke their API tokens. Their assignments and comments will remain." GitHub's branch protection rule changes show: "Changes to this setting will take effect immediately and will apply to all new pull requests." The consequence preview belongs directly under the control -- not in a tooltip, help article, or post-action confirmation where the user encounters it too late to influence their decision.
Group settings by user goal, not technical category. A "Notifications" page that groups items by technical delivery channel (Email, Push, SMS, In-app) forces users to hunt for the event they care about across four sections. A goal-based grouping asks: "When do I want to be notified?" and groups by event type (Mentions, Comments, Assignments, Deadlines). GitHub reorganized its notification settings from channel-first to event-first in 2020 and reported significant reduction in user confusion about notification routing. The test: can the user find the setting for "mentions from teammates" without reading every section heading? If finding a setting requires reading and understanding the entire page structure, the grouping is technical rather than goal-oriented.
Write dangerous settings with visual and copy separation. Settings that are destructive, irreversible, or have wide scope (delete account, revoke all API keys, make repository public) should be physically separated from routine settings with a visually distinct section. GitHub's "Danger Zone" section is the canonical example -- red border, distinct section heading, and each setting in its own card with a specific warning. The copy inside a danger zone setting should state the scope explicitly: "This will permanently delete your account and all associated data, including repositories, packages, and gists. This action cannot be undone." Every dangerous setting gets its own action button, never a toggle -- toggles imply reversibility, which is incompatible with the user's mental model of destructive actions.
Help text answers "why would I change this?" -- not "what does this do?" The label tells the user what the setting controls. The help text should answer the question the user is most likely to have: when would I want this on or off? Stripe's API key settings show help text: "Use restricted keys to give third-party services only the permissions they need." This tells the user the use case, not the definition of a restricted key. Apple's location services help text says "Apps that have requested to use your location are listed here. You can change or remove access at any time" -- not a definition of location services but guidance on the action the user might want to take. Write the help text by imagining the question a user would type into your support chat before finding the setting on their own.
Settings labels must work without reading surrounding context. A settings page is often reached from search, deep links, or system notifications -- the user may not have scrolled past the page heading. Each label and toggle must be independently comprehensible. "Enable this" as a label is useless without the surrounding context. "Marketing emails" as a label is ambiguous -- is this emails I send or emails I receive? "Receive marketing emails from Acme" removes the ambiguity and works whether the user reaches this toggle from the page's top or from a search result highlighting this specific control. Slack's notification settings work at any zoom level or search result because every label includes the actor and event: "Notify me when I'm mentioned in a channel."
Toggles have two states and one label. The label must be accurate and meaningful in both states. Use this decision tree:
The label should NOT include words like "Enable," "Toggle," or "Turn on" -- the toggle UI element handles that semantics. The label should NOT include the current state: "Status: Active" as a toggle label is broken because it reads "Status: Active: OFF" when disabled. Document the chosen pattern convention in the design system so all future toggle labels default to the correct form.
Notification preference panels are among the most complex settings UIs in consumer software. The best implementations use a two-axis model:
| Push | In-App | ||
|---|---|---|---|
| Mentions | [toggle] | [toggle] | [toggle] |
| Comments | [toggle] | [toggle] | [toggle] |
| Assignments | [toggle] | [toggle] | [toggle] |
| Due dates | [toggle] | [toggle] | [toggle] |
Each cell is independently controllable. Column headers name the delivery channel; row headers name the event. This lets a user who wants push-only mentions and email-only due dates express exactly that preference without hunting through multiple sections. The pattern scales to any combination of events and channels. GitHub's notification preferences, Slack's notification granularity, and Figma's comment notifications all approximate this model. Label the row headers with event names from the user's perspective ("Someone mentions me") rather than system event names ("mention_created").
Use this checklist before shipping or reviewing any settings page implementation:
| Check | Criteria | Pass Condition |
|---|---|---|
| Toggle label form | Labels are noun phrases, not state descriptions | No labels with "Enable," "Status: ON/OFF," or current state in text |
| Effect description | Description explains user-facing effect | Description does not restate the label; explains trigger or outcome |
| Consequence previews | Significant side-effects have inline preview | Preview text appears beneath the control before interaction |
| Goal-based grouping | Settings grouped by user goal | Section headings name user goals, not technical subsystems |
| Dangerous separation | Irreversible settings are visually separated | Danger zone has distinct border, heading, and button (not toggle) |
| Help text answers "why" | Help text explains when to change the setting | No help text that is just a restatement or definition of the label |
| Context-independence | Labels work without surrounding section heading | Label is self-contained; "enable this" or "the above" never appears |
| Dangerous settings use buttons | No dangerous action is a toggle | Toggle is never used for delete, terminate, or irreversible actions |
The Technical Label. Settings labeled with backend terminology that means nothing to the user. "Enable WebSocket fallback," "Use legacy authentication flow," "Disable CORS preflight caching." Before: "Enable compression artifacts reduction." After: "Reduce blurriness when viewing large images on slower connections." The test: would a user who did not write this feature understand the label without reading documentation? Technical labels are a symptom of settings being written by engineers for engineers -- they describe implementation details rather than user outcomes. Every technical label in a settings panel is a support ticket waiting to happen.
The Context-Dependent Toggle. A toggle whose label changes meaning based on its position in the page hierarchy. A toggle that says "Enabled" inside a section titled "Push Notifications" reads correctly inline, but if the user reaches it via search or deep link, "Enabled" conveys nothing. Before: toggle labeled "Enabled" inside the "Marketing Emails" section. After: standalone toggle labeled "Marketing emails from Acme Corp." The rule: any toggle that would be meaningless if its containing section heading were removed is context-dependent and needs to be rewritten. This pattern is especially common in settings pages built incrementally, where new toggles are added to existing sections by developers who rely on the section heading for context.
The Consequence Surprise. Significant settings with no consequence preview, where the user discovers the effect only after taking the action. Turning off two-factor authentication with no warning, then discovering the next login requires a backup code that was never saved. Before: toggle "Two-factor authentication" with no description. After: "Two-factor authentication -- Disable this only if you have a backup authentication method. Disabling will not affect active sessions but will remove 2FA requirements on your next login." The consequence preview reduces regret-driven support tickets and builds user trust by treating users as partners in understanding the product's behavior rather than recipients of unexplained system actions.
The Ungrouped Dump. A settings page with 30-50 items in a single list, organized alphabetically or in the order they were added to the codebase. Before: a flat list of 40 toggles with no section dividers. After: grouped into "Notifications," "Appearance," "Privacy," "Advanced," with each group answering a distinct user goal and dangerous settings separated into their own section with visual treatment. The ungrouped dump is the most common settings page failure in products that have grown incrementally -- new settings are added at the bottom of the list because that is the easiest code change, not because it is the best placement for the user. A quarterly settings audit that re-evaluates grouping and ordering prevents the dump from accumulating.
Slack notification preferences. Slack's notification preferences are a benchmark for the industry. The top-level structure separates "My preferences" (global defaults) from per-workspace and per-channel overrides -- a hierarchy that reflects how users actually think about notification scope. Inside each section, the controls use event-based labels: "Direct messages, mentions, and keywords," "All new messages," "Nothing." The keyword notification field shows an inline example: "Add words or phrases, separated by commas. Example: design review, Q4 launch." The consequence of each setting is visible: changing to "Nothing" in a channel shows "You'll stop being notified for this channel" immediately beneath the radio button. This real-time consequence preview is the product's acknowledgment that notification settings are consequential and users should understand the effect before they commit.
GitHub notification settings. GitHub's 2020 notification redesign moved from a channel-centric model to an event-centric one. The current settings page groups notifications by where they come from (Participating, Watching, Ignoring) and lets users set delivery channel independently per category. Each category includes a one-sentence explanation of what "participating" or "watching" means in practice: "Participating means you were mentioned, committed to the repository, or commented in a thread." This explanation is essential -- GitHub-specific vocabulary like "watching" has a precise meaning that differs from casual use. The settings page teaches the vocabulary at the point of decision, which is more effective than a glossary users must navigate to separately when they encounter an unfamiliar term.
Figma editor preferences. Figma's editor preferences are embedded in the product experience rather than a separate settings page -- accessible via the menu during active work. Preferences like "Show ruler," "Snap to objects," and "Clip content" use verb phrases that describe the visual or behavioral effect rather than technical feature names. The "Clip content" toggle, which controls whether content outside a frame is visible or hidden, includes a small diagram showing the before/after visual result -- copy alone cannot convey a spatial concept. This hybrid of label plus diagram is a pattern to adopt for any setting with a visual effect that words struggle to describe accurately. Figma's decision to embed preferences in the editor rather than a separate settings page reduces the distance between discovering a preference and changing it.
Apple System Settings organization. Apple's System Settings (formerly System Preferences) uses a goal-based top-level organization: "Wi-Fi," "Bluetooth," "Notifications," "Focus," "Screen Time," "General." Each top-level item answers "what am I managing?" not "what subsystem does this configure?" Inside "Notifications," the structure is alphabetical by app name -- which is correct because the user arrives with a specific app in mind, not a general notification concept. Apple places consequence text inline for dangerous settings: "Erasing all content and settings will remove all media, data, and settings from this Mac. This action cannot be undone." The placement is immediately before the action button, not in a separate help section the user might skip. Apple's pattern of making consequence text non-collapsible and always visible demonstrates the company's position that users should be fully informed before acting on settings with significant effects.
These are fill-in-the-blank templates for the most common settings and preferences copy patterns:
[Noun phrase] -- e.g., "Email digests," "Two-factor authentication"Allow [actor] to [action] -- e.g., "Allow teammates to see your active status"[Behavior that results] -- e.g., "Play a sound when a message arrives"Get [notification / alert] when [event].[Outcome] when this is enabled. [Outcome] when disabled.[Action] will [effect] immediately. [Downstream effect].[Specific action] -- e.g., "Delete account," "Revoke all API keys"This will permanently [effect]. [Downstream effects]. This action cannot be undone.Use this when [scenario]. Change this if [condition].[Actor] [event] -- e.g., "Someone mentions me," "A task is assigned to me"[What the user is managing] -- e.g., "Notifications," "Privacy," "Security"[Setting name] · Required by your organizationInventory every setting in scope. For each setting, answer three questions: what happens when this is on? What happens when this is off? What is the consequence if changed accidentally? This inventory drives all subsequent copy decisions. Settings with significant or irreversible consequences on change are flagged for consequence preview copy. Settings with technical or ambiguous labels are flagged for rewriting before any description is written.
Write the label as a noun phrase describing what is controlled. Write the description as a sentence explaining the effect from the user's perspective, starting with the trigger or the outcome: "Get an email when..." or "Hides your profile from..." Test each label-plus-description pair by asking: could a user understand this toggle without reading the rest of the page? If not, the label is context-dependent and needs revision.
Identify settings with significant side effects. For each flagged setting, write consequence preview copy and place it directly beneath the control -- not in a tooltip, not in a help link, not in a post-action confirmation. Review the consequence preview with engineering to confirm technical accuracy. The consequence preview for a setting that logs out all other sessions must confirm with engineering whether the current session is affected.
Group settings by user goal. List all settings and sort them into goal-oriented groups. Name each group with a heading that answers "what is the user trying to manage?" not "what technical subsystem is this?" Test the groupings by describing them to a user unfamiliar with the settings page and asking them which group each setting belongs to -- if their answers match the groupings, the structure is goal-oriented. If they consistently place settings in different groups, revise the headings.
Identify and separate dangerous or irreversible settings. Move them to a visually distinct section with explicit scope copy and a button (not toggle) that leads to a confirmation dialog. Review the complete settings page with a fresh-eyes pass to confirm that no destructive setting is within accidental-click distance of a routine setting -- proximity accidents are a real risk in settings UIs with dense, small toggle controls.
Many operating systems and enterprise products offer a settings search that filters the settings page to matching controls. When a user types "notification" in macOS System Settings, matching controls are highlighted in-place. This behavior requires that every toggle label and description contain the vocabulary users would naturally type when searching for that setting. If the label is "Alerts" but users search for "notifications," the setting is invisible to search. Audit settings labels against the most common support queries about settings to identify vocabulary mismatches and adjust labels to match user language.
Deep-linked settings (links shared in onboarding emails, help articles, or admin notifications that take users directly to a specific setting) place users in the middle of the settings page without the surrounding context that guides the reading experience. Every setting that is deep-linked should have a short descriptive paragraph or call-out box explaining why the user was sent there: "Your admin has asked you to enable two-factor authentication. Turn on the toggle below to secure your account." This contextual frame bridges the gap between the message that sent the user here and the control they need to interact with.
Settings that have changed since the user last visited should surface a change indicator: a "New" badge, a banner, or a highlighted border. When a setting change was forced by an admin or a product update, the copy must acknowledge this: "Your organization requires two-factor authentication. This setting was enabled by your admin and cannot be changed." Surfacing admin-enforced settings with honest copy prevents users from filing support tickets about why they cannot toggle a control that appears interactive.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeApplies progressive disclosure to forms, settings, and panels — shows primary options first and reveals secondary/advanced options on demand to reduce cognitive load.
Authors or migrates Obsidian community plugin setting tabs using the declarative getSettingDefinitions() API (Obsidian 1.13.0+) with optional fallback for older app versions.
Guides writing clear, concise, human-voiced UI microcopy for buttons, errors, tooltips, and empty states.