From ce301f450c33b4e92ff3ada98eb9fb5665ceb0df Mon Sep 17 00:00:00 2001 From: Heather Barranco Date: Thu, 9 Apr 2026 10:09:02 -0400 Subject: [PATCH] feat(apollo-wind): expand apollo-writing skill with full guidelines and content patterns Replaces the condensed SKILL.md with the full UX writing guidelines, including new active/passive voice guidance and we/you distinction for error messages. Adds 16 content pattern files covering buttons, errors, empty states, modals, forms, navigation, tooltips, tables, and more. Co-Authored-By: Claude Sonnet 4.6 --- ...ion and disclosure copy content pattern.md | 76 +++ .../Button and CTA copy content pattern.md | 82 +++ .../apollo-writing/Content pattern index.md | 148 +++++ ... time and duration copy content pattern.md | 93 +++ .../Destructive modal copy content pattern.md | 70 ++ .../Drawer copy content pattern.md | 77 +++ .../Empty state content pattern.md | 70 ++ .../Error message content pattern.md | 72 ++ .../Form field copy content pattern.md | 78 +++ .../Link copy content pattern.md | 63 ++ .../Notification copy content pattern.md | 86 +++ .../skills/apollo-writing/SKILL.md | 623 ++++++++++++++---- .../Search and filter copy content pattern.md | 87 +++ .../Table and status copy content pattern.md | 104 +++ ...abs and navigation copy content pattern.md | 85 +++ ...ggle and selection copy content pattern.md | 87 +++ .../Tooltip copy content pattern.md | 61 ++ 17 files changed, 1842 insertions(+), 120 deletions(-) create mode 100644 packages/apollo-wind/skills/apollo-writing/Accordion and disclosure copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Button and CTA copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Content pattern index.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Date time and duration copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Destructive modal copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Drawer copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Empty state content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Error message content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Form field copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Link copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Notification copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Search and filter copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Table and status copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Tabs and navigation copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Toggle and selection copy content pattern.md create mode 100644 packages/apollo-wind/skills/apollo-writing/Tooltip copy content pattern.md diff --git a/packages/apollo-wind/skills/apollo-writing/Accordion and disclosure copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Accordion and disclosure copy content pattern.md new file mode 100644 index 000000000..c83e0427e --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Accordion and disclosure copy content pattern.md @@ -0,0 +1,76 @@ +# Accordion and disclosure copy content pattern + +--- +name: accordion-and-disclosure-copy +description: generate product ui accordion and disclosure copy following ux writing guidelines. use when drafting or revising accordion labels, show or hide triggers, view details links, advanced settings labels, expandable summaries, or disclosure text during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for accordion and disclosure UI. + +Interpret the user's request in natural language. Extract, when available: +- what content is being expanded or collapsed +- whether the request is for an accordion label, disclosure trigger, section heading, summary text, or supporting helper copy +- whether the content is advanced, optional, supplementary, or detail-level information +- whether the trigger should reveal or collapse content +- any product-specific terminology that should be used + +Return only the fields that apply, omitting any that aren't needed: + +Section heading: ... +Expand label: ... +Collapse label: ... +Summary text: ... +Helper text: ... + +## Rules +- Use sentence case throughout. +- Keep labels short, clear, and specific. +- Use clear, neutral triggers for expandable content. +- Prefer straightforward labels such as Show advanced settings, View details, or Expand task history. +- Avoid casual, playful, or vague language such as Sneak peek, Unlock more, or See magic. +- Make the expanded content obvious from the label. +- Use noun-based section headings, not action phrases. Headings should describe what the section is, not what the user should do. +- Keep summary text short and scannable. +- Use helper text only when it adds necessary context. +- Avoid blame, filler, idioms, exclamation points, jargon, and dramatic language. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Accordion label** +- Name the content being revealed. +- Keep it neutral and descriptive. + +**Expand label** +- Use Show, View, or Expand when the action reveals content. +- Be explicit about what appears. + +**Collapse label** +- Use Hide when the collapse label pairs with Show (e.g. Show advanced settings → Hide advanced settings). +- For View or Expand triggers, keep the collapse label parallel (e.g. View details → Hide details, Expand task history → Collapse task history). +- Do not use Close or Dismiss as collapse labels. + +**Advanced settings** +- Use direct labels such as Show advanced settings. +- Avoid implying mystery, reward, or surprise. + +**Section heading** +- Use noun-based headings that describe the section content. +- Do: "Process overview", "Configuration details", "Output parameters" +- Don't: "Learn about processes", "Configure the settings", "View output" + +**Summary text** +- Briefly describe what is inside the section when helpful. +- Keep it to 1 short sentence. + +## Examples of requests this skill should handle +- "Write accordion labels for advanced settings" +- "Draft expand and collapse labels for task history" +- "I need disclosure copy for viewing process details" +- "Rewrite this accordion UI to match our design system voice" + +## Output example +**Section heading:** Configuration details +**Expand label:** Show advanced settings +**Collapse label:** Hide advanced settings +**Summary text:** Review configuration options for this automation. diff --git a/packages/apollo-wind/skills/apollo-writing/Button and CTA copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Button and CTA copy content pattern.md new file mode 100644 index 000000000..ef56bb6f9 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Button and CTA copy content pattern.md @@ -0,0 +1,82 @@ +# Button and CTA copy content pattern + +--- +name: button-and-cta-copy +description: generate product ui button labels and call-to-action copy following ux writing guidelines. use when drafting or revising primary buttons, secondary buttons, link ctas, menu actions, destructive actions, retry actions, or button sets during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style button and CTA copy for product UI. + +Interpret the user's request in natural language. Extract, when available: +- what action the user is taking +- what object the action applies to +- whether the action is primary, secondary, destructive, recovery, navigation, or menu-based +- whether the object already exists or is being created +- whether platform-specific terminology should be applied +- whether a paired button set is needed + +Return only the fields that apply, omitting any that aren't needed: + +Primary CTA: ... +Secondary CTA: ... +Link CTA: ... +Menu action: ... + +## Rules +- Use sentence case throughout. +- Keep CTAs short, clear, and specific. Keep labels to 2–4 words maximum when possible. +- Prefer verb + noun when the object is not obvious from context. +- Do not use vague labels such as "Click here", "Learn more", "Go", "Submit", "Confirm", or "Continue" unless the context truly makes them the clearest option. +- Use specific destination or action language for links. Do not use the word "link" in link text — screen readers announce it automatically. Use consistent link text across pages when linking to the same destination. +- Use Build for agents, automations, or apps. +- Use Create for creating a new object that did not exist before. +- Use Add for adding an existing object to an existing list, group, view, or container. +- Use "Create new" or "Build new" only when a button triggers a dropdown for users to select from multiple object types — in this case "new" acts as the object. Do not use New as a standalone verb or in place of Create or Add. +- Use Select instead of Choose for clickable UI choices. +- Use Try again instead of Retry. +- Use Delete for permanent removal. +- Use Remove for taking something out of a list, group, or container without deleting it. +- Do not use Execute in the context of automations or jobs. +- Use Run as a verb only (e.g. "Run automation"). Never use Run as a noun — use Job instead. +- Avoid jargon, filler, idioms, exclamation points, and dramatic language. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Primary CTA** +- Use the clearest action for the next step. +- Prefer specific action labels over generic progression labels. + +**Secondary CTA** +- Use a safe supporting action such as Cancel, Back, Discard, or Clear when appropriate. + +**Link CTA** +- Make the destination or outcome obvious. +- Do not use "Learn more" or "Click here". +- Do not include the word "link" in the text. + +**Recovery CTA** +- Use Try again when an action failed and the user should repeat it. +- Make sure the surrounding copy explains what happened. + +**Create vs Build vs Add** +- Use Build for agents, automations, or apps. +- Use Create for new objects such as projects, users, templates, or datasets. +- Use Add for existing objects being placed into an existing container. +- Use "Create new" or "Build new" only when triggering a multi-type dropdown. + +**Destructive CTA** +- Use Delete for permanent removal. +- Use Remove when the object remains elsewhere. + +## Examples of requests this skill should handle +- "Write a primary button for creating a project" +- "Draft CTA labels for building an automation" +- "I need a retry button for a failed upload" +- "Rewrite these actions to match our design system voice" +- "Write a primary and secondary button set for removing a user from a workspace" + +## Output example +**Primary CTA:** Build automation +**Secondary CTA:** Cancel +**Link CTA:** Manage access diff --git a/packages/apollo-wind/skills/apollo-writing/Content pattern index.md b/packages/apollo-wind/skills/apollo-writing/Content pattern index.md new file mode 100644 index 000000000..1cea51846 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Content pattern index.md @@ -0,0 +1,148 @@ +# Content pattern index + +A reference guide to all content generation patterns in this library. Each pattern produces production-style UI copy aligned with the UX writing guidelines. + +**Foundation:** [UX writing guidelines.md](UX%20writing%20guidelines.md) + +--- + +## Content and messaging + +### Error message +**File:** [Error message content pattern.md](Error%20message%20content%20pattern.md) +**Use for:** Inline validation errors, form errors, banner errors, toast errors, upload errors, permissions errors, system errors. +**Output:** Title, Body, CTA — fields vary by component type (inline = body only; toast = body + optional CTA; modal/full-page = all three). +**See also:** Notification copy pattern for success, warning, and info states. + +--- + +### Notification +**File:** [Notification copy content pattern.md](Notification%20copy%20content%20pattern.md) +**Use for:** Success toasts, warning alerts, info banners, inline status messages, action notifications. +**Output:** Title, Body, Primary CTA, Secondary CTA, Link CTA — fields vary by notification type. +**See also:** Error message pattern for detailed error copy guidance. + +--- + +### Empty state +**File:** [Empty state content pattern.md](Empty%20state%20content%20pattern.md) +**Use for:** First-use states, no-results states, filtered empty states, no-data states, post-action empty states. +**Output:** Title, Body, Primary CTA, Secondary CTA, Link — omit fields that don't apply. + +--- + +## Actions and controls + +### Button and CTA +**File:** [Button and CTA copy content pattern.md](Button%20and%20CTA%20copy%20content%20pattern.md) +**Use for:** Primary buttons, secondary buttons, menu actions, destructive actions, recovery actions, button sets. +**Output:** Primary CTA, Secondary CTA, Link CTA, Menu action — omit fields that don't apply. +**Key rules:** Build for automations/agents/apps. Create for new objects. Add for existing objects into containers. Try again not Retry. Run is a verb — Job is the noun. + +--- + +### Link +**File:** [Link copy content pattern.md](Link%20copy%20content%20pattern.md) +**Use for:** Inline links, action links, help links, documentation links, navigation links. +**Output:** Link text only. +**Key rules:** No "Learn more" or "Click here". Do not use the word "link" in link text. Consistent text across pages for the same destination. + +--- + +### Toggle and selection +**File:** [Toggle and selection copy content pattern.md](Toggle%20and%20selection%20copy%20content%20pattern.md) +**Use for:** Toggle labels, checkbox labels, radio groups, dropdown labels and options, people picker helper text, selection instructions. +**Output:** Control type, Label, Helper text, Options — omit fields that don't apply. +**Key rules:** Select not Choose. Clear not Deselect. No two options start with the same word or phrase. + +--- + +### Destructive modal +**File:** [Destructive modal copy content pattern.md](Destructive%20modal%20copy%20content%20pattern.md) +**Use for:** Delete confirmations, removal confirmations, unsaved changes dialogs, exit confirmations, access revocation. +**Output:** Title, Body, Secondary CTA, Primary CTA — Secondary CTA is optional. +**Key rules:** Delete for permanent removal. Remove for non-permanent. Revoke access for access revocation. Only say "can't undo" when truly irreversible. + +--- + +## Forms and inputs + +### Form field +**File:** [Form field copy content pattern.md](Form%20field%20copy%20content%20pattern.md) +**Use for:** Text input labels, placeholder text, helper text, inline validation errors, checkbox labels, dropdown labels, toggle labels, people picker guidance. +**Output:** Label, Placeholder, Helper text, Error — omit fields that don't apply. +**See also:** Search and filter pattern for search field copy. Error message pattern for complex inline error scenarios. + +--- + +### Search and filter +**File:** [Search and filter copy content pattern.md](Search%20and%20filter%20copy%20content%20pattern.md) +**Use for:** Search field labels and placeholders, filter labels, filter reset actions, no-results states, filtered empty states, result summaries. +**Output:** Search field label, Search field placeholder, Filter label, Helper text, Empty state title, Empty state body, Primary CTA, Secondary CTA — omit fields that don't apply. +**Key rules:** Always include a label for search fields. "Clear all filters" or "Reset filters" — not "Cancel" or "X". + +--- + +## Layout and navigation + +### Tabs and navigation +**File:** [Tabs and navigation copy content pattern.md](Tabs%20and%20navigation%20copy%20content%20pattern.md) +**Use for:** Tab labels, page headings, section headings, side navigation labels, breadcrumb labels, menu navigation items. +**Output:** Page heading, Section heading, Tab labels, Navigation items, Breadcrumb label — number of tab and nav fields matches the request. +**Key rules:** Noun-based headings only. First tab = most logical starting view. Related tabs adjacent. + +--- + +### Drawer +**File:** [Drawer copy content pattern.md](Drawer%20copy%20content%20pattern.md) +**Use for:** Drawer and side panel headers, section headings, body copy, Save/Apply/Cancel/Discard CTA sets. +**Output:** Header, Section heading, Body, Primary CTA, Secondary CTA — omit fields that don't apply. +**See also:** Form field pattern for input copy within drawers. + +--- + +### Accordion and disclosure +**File:** [Accordion and disclosure copy content pattern.md](Accordion%20and%20disclosure%20copy%20content%20pattern.md) +**Use for:** Accordion labels, show/hide triggers, advanced settings labels, expandable summaries, section headings. +**Output:** Section heading, Expand label, Collapse label, Summary text, Helper text — omit fields that don't apply. +**Key rules:** Show/Hide, View/Hide, Expand/Collapse — keep pairs parallel. No casual language (Sneak peek, Unlock more). + +--- + +## Data display + +### Table and status +**File:** [Table and status copy content pattern.md](Table%20and%20status%20copy%20content%20pattern.md) +**Use for:** Table column labels, status badges, row actions, timestamp labels and formats, duration labels, empty table states. +**Output:** Column label, Status badge, Row action, Timestamp label, Timestamp format, Duration label, Empty state title, Empty state body — omit fields that don't apply. +**See also:** Date, time, and duration pattern for detailed formatting rules. + +--- + +### Tooltip +**File:** [Tooltip copy content pattern.md](Tooltip%20copy%20content%20pattern.md) +**Use for:** Icon button tooltips, truncated value tooltips, timestamp tooltips, inline guidance tooltips, status tooltips. +**Output:** Tooltip text only. +**Key rules:** Supplementary content only — never for critical info, errors, or interactive content. 1–2 lines max (exception: list-style tooltips). Always include timezone in timestamp tooltips. + +--- + +### Date, time, and duration +**File:** [Date time and duration copy content pattern.md](Date%20time%20and%20duration%20copy%20content%20pattern.md) +**Use for:** Timestamp labels, relative and absolute time formatting guidance, duration labels, date picker helper text, time-based table labels. +**Output:** Label, Format guidance, Helper text, Tooltip — omit fields that don't apply. +**Key rules:** Date format: ddd, MMM D, YYYY. Time format: H:MM AM/PM timezone. Duration: exact (2h 15m 30s) or rounded (2.25 hrs) with tooltip. Never mix micro and macro time units. + +--- + +## Cross-references + +| If you need… | Use this pattern | And also consider… | +|---|---|---| +| Error copy | Error message | Notification (for error banners/toasts) | +| Success or warning copy | Notification | — | +| Search field copy | Search and filter | Form field (for other input types) | +| Inline validation error | Error message | Form field (for the field label and helper text) | +| Table timestamps or durations | Table and status | Date, time, and duration (for format detail) | +| Drawer form inputs | Drawer | Form field | +| Button on a destructive modal | Destructive modal | Button and CTA | diff --git a/packages/apollo-wind/skills/apollo-writing/Date time and duration copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Date time and duration copy content pattern.md new file mode 100644 index 000000000..43b82d439 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Date time and duration copy content pattern.md @@ -0,0 +1,93 @@ +# Date, time, and duration copy content pattern + +--- +name: date-time-and-duration-copy +description: generate product ui date, time, timestamp, and duration copy following ux writing guidelines. use when drafting or revising timestamp labels, relative and absolute time formatting guidance, duration labels, date-picker helper text, time-based table labels, or related temporal product ui copy during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for date, time, timestamp, and duration UI. + +Interpret the user's request in natural language. Extract, when available: +- whether the request is for a timestamp label, timestamp format, duration label, date-picker guidance, helper text, tooltip text, or table column label +- whether users need quick recency scanning or precise reference +- whether the time shown is recent, historical, scheduled, or duration-based +- whether the UI is in a table, form, tooltip, detail page, or log view +- any product-specific terminology that should be used + +Return only the fields that apply, omitting any that aren't needed: + +Label: ... +Format guidance: ... +Helper text: ... +Tooltip: ... + +## Rules +- Use sentence case throughout. +- Keep labels short, clear, and specific. +- Use Last updated as the label for update-time columns and fields. +- Use relative time when users need to quickly scan recent activity. Use absolute time when users need precision or exact reference. +- When relative time is shown in a table or list, use a tooltip to show the absolute date and time including the timezone. +- Use consistent date and time formatting within the same experience. In tables, align dates to the left and use a uniform format across all columns. +- Use numerals for all dates, times, and durations. + +### Date format +- Format: ddd, MMM D, YYYY (e.g. Mon, Dec 12, 2023) +- No leading zero on the day. Year can be omitted for events in the current year. +- Use the full date in cards and wherever space allows. + +### Time format +- Express time as H:MM AM/PM timezone (e.g. 4:12 PM UTC) +- Hour without leading zero; minutes with leading zero. +- Include a space before AM or PM. No periods (AM not A.M.). +- Always include the timezone. +- Noon and midnight may be expressed as "Noon" / "Midnight" or "12 PM" / "12 AM". + +### Duration format +- Use Duration (not execution time or throughput time). +- Exact duration: 00x 00y 00z format (e.g. 2h 15m 30s). Always include the unit letter after the number. +- Rounded duration: 00.00 xyz format (e.g. 2.25 hrs). Max two decimal places. Show exact time on hover in a tooltip. +- Display up to three consecutive units starting with the highest (e.g. 1h 00m 30s, not 1h 30s). +- Never mix micro time (h/m/s) with macro time (y/w/d) in the same value. + +### Last updated cell values +- Do: "Updated just now", "Updated 5 minutes ago", "Updated 1 hour ago", "Updated May 30, 2025", "Updated May 30, 2025 at 4:12 PM" +- Don't: "Updated recently", "Last modified", "Date of change" +- Use relative time for updates within the last 24 hours. Switch to absolute time after that. + +## Patterns + +**Update timestamp** +- Use Last updated as the label. +- Use relative time for recent changes when scanning matters. +- Show absolute time including timezone on hover when relative time appears in a table or list. + +**Log or audit timestamp** +- Use absolute time when users need exact sequencing or precise reference. +- Show seconds and timezone when required. + +**Duration label** +- Use Duration. +- Keep the format consistent within the same table or screen. +- Use exact format for precision; rounded format with tooltip for scannability. + +**Date picker helper text** +- Add helper text only when users need input guidance, constraints, or formatting help. + +**Scheduled date or time** +- Use explicit labels that describe what the date represents, such as Start date or End time. + +**Tooltip** +- Use the tooltip to show the full absolute date and time including timezone when the UI shows relative time. +- Format: Month D, YYYY at H:MM AM/PM timezone (e.g. December 12, 2025 at 4:12 PM UTC) + +## Examples of requests this skill should handle +- "Write a label and format rule for a last updated column" +- "Draft helper text for a date picker with a required start date" +- "I need copy for showing relative time in a jobs table" +- "Write a duration label for a run history table" +- "Rewrite this timestamp UI to match our design system voice" + +## Output example +**Label:** Last updated +**Format guidance:** Show relative time in the table cell for updates within the last 24 hours. Show the absolute date and time on hover. Use absolute time in logs and detail views where precision matters. +**Tooltip:** December 12, 2025 at 4:12 PM UTC diff --git a/packages/apollo-wind/skills/apollo-writing/Destructive modal copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Destructive modal copy content pattern.md new file mode 100644 index 000000000..eecf60960 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Destructive modal copy content pattern.md @@ -0,0 +1,70 @@ +# Destructive modal copy content pattern + +--- +name: destructive-modal-copy +description: generate copy for destructive or confirmation modals following ux writing guidelines. use when drafting or revising modal title, body, and cta text for actions like delete, remove, discard, leave, revoke, or other high-risk confirmation flows during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for a destructive confirmation modal. + +Interpret the user's request in natural language. Extract, when available: +- action +- object +- consequence +- whether the action is permanent or reversible +- any important context such as access loss, data removal, or unsaved changes + +Return only the fields that apply. Secondary CTA is optional — omit it if the modal only requires a single action. + +Title: ... +Body: ... +Secondary CTA: ... +Primary CTA: ... + +## Rules +- Use sentence case throughout. +- Write a direct, descriptive title, usually as a question. +- Keep body copy to 1–2 short sentences. +- State what will happen. +- If there is a meaningful consequence, include it. +- Only say the action cannot be undone when it is truly irreversible. +- Use Delete for permanent removal. +- Use Remove for taking something out of a list, group, or container without deleting it. +- Use specific CTA labels, not generic labels. Keep CTAs to 2–4 words with a verb + noun structure where possible. +- Default secondary CTA to Cancel unless the user's context clearly calls for a different safe option. +- Avoid blame, filler, idioms, exclamation points, and dramatic language. +- Use contractions sparingly. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Examples of requests this skill should handle +- "Write copy for a modal to delete an automation" +- "I need a confirmation dialog for removing a user from a workspace" +- "Draft title/body/button text for discarding unsaved changes" +- "Rewrite this delete modal to match our design system voice" + +## Modal patterns + +**Permanent deletion** +- Title should clearly name the action and object. +- Body should explain what will be removed and whether it can be undone. +- Primary CTA should be Delete + object when helpful. + +**Non-destructive removal** +- Use Remove, not Delete. +- Explain what access, association, or placement is changing. +- Do not imply permanent loss unless true. + +**Unsaved changes or exit confirmation** +- Be explicit about losing edits or leaving the current flow. +- Prefer concise, plain-language consequences. + +**Access revocation** +- State whose access is being revoked and to what. +- Clarify whether the person can be re-added or access restored. +- Use Revoke access as the primary CTA, not Delete or Remove. + +## Output example +**Title:** Delete this automation? +**Body:** This will permanently delete the automation and all associated logs. You can't undo this action. +**Secondary CTA:** Cancel +**Primary CTA:** Delete automation diff --git a/packages/apollo-wind/skills/apollo-writing/Drawer copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Drawer copy content pattern.md new file mode 100644 index 000000000..e9a759cd4 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Drawer copy content pattern.md @@ -0,0 +1,77 @@ +# Drawer copy content pattern + +--- +name: drawer-copy +description: generate product ui drawer copy following ux writing guidelines. use when drafting or revising drawer headers, section headings, helper text, save and cancel actions, side panel body copy, or setup and edit panel content during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for a drawer or side panel. + +Interpret the user's request in natural language. Extract, when available: +- what the drawer is for +- whether the drawer is for creating, editing, configuring, reviewing, or selecting something +- whether the request is for a header, section heading, helper text, CTA set, or full drawer copy +- whether the body includes forms, settings, or supporting guidance +- whether the panel needs Save, Apply, Cancel, or Discard actions +- any product-specific terminology that should be used + +Return only the fields that apply, omitting any that aren't needed: + +Header: ... +Section heading: ... +Body: ... +Primary CTA: ... +Secondary CTA: ... + +## Rules +- Use sentence case throughout. +- Make the header clearly state the purpose of the panel. Keep it short, direct, and specific. +- Use noun-based section headings for grouped content. Group related fields under labeled sections to support skimming. +- Use body copy only when it helps the user act or understand the panel. Avoid redundant instructions when the form fields already provide enough guidance. +- For drawers containing form inputs, refer to the form field copy content pattern for label, placeholder, helper text, and inline error guidance. +- Keep body copy to 1–2 short sentences when used. +- Use one clear primary action, typically Save or Apply. Keep CTA labels to 2–4 words with a verb + noun structure where possible. +- Use a secondary action such as Cancel or Discard when needed. +- Use specific CTA labels consistent with system terminology. Avoid vague labels such as Confirm, Submit, or Continue unless the context truly makes them the clearest option. +- Use Build for agents, automations, or apps. +- Use Create for new objects that did not exist before. +- Use Add for adding an existing object to an existing list, group, or container. +- Use Select instead of Choose for clickable UI choices. +- Avoid blame, filler, idioms, exclamation points, jargon, and dramatic language. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Edit drawer** +- Use a direct header such as Edit project settings. +- Use Save as the primary CTA when changes are committed. + +**Apply/configure drawer** +- Use a header that names the setting or configuration area. +- Use Apply when the action applies filters, settings, or scoped changes. + +**Create/setup drawer** +- Use a header that names what is being created or set up. +- Use Create or Build only when the drawer completes the creation action. + +**Selection drawer** +- Use a header that tells users what they are selecting. +- Keep section headings noun-based and scannable. +- Use Select, not Choose, for the primary action. + +**Discarding changes** +- Use Discard only when changes will be lost. +- Use Cancel when the drawer simply closes without emphasizing loss. + +## Examples of requests this skill should handle +- "Write a drawer header and CTA set for editing project settings" +- "Draft section headings for a side panel with automation details" +- "I need copy for a drawer that lets users apply filters" +- "Rewrite this drawer to match our design system voice" + +## Output example +**Header:** Edit project settings +**Section heading:** Access and permissions +**Body:** Changes apply to all members of this project. +**Primary CTA:** Save +**Secondary CTA:** Cancel diff --git a/packages/apollo-wind/skills/apollo-writing/Empty state content pattern.md b/packages/apollo-wind/skills/apollo-writing/Empty state content pattern.md new file mode 100644 index 000000000..f2de74f45 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Empty state content pattern.md @@ -0,0 +1,70 @@ +# Empty state content pattern + +--- +name: empty-state-copy +description: generate product ui empty state copy following ux writing guidelines. use when drafting or revising empty state title, body, and cta text for tables, lists, dashboards, search results, filters, first-use experiences, or no-data states during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for an empty state. + +Interpret the user's request in natural language. Extract, when available: +- what content or object is missing +- whether this is first use, no results, filtered results, or a cleared/removed state +- what the user was trying to do +- what action the user can take next +- whether a primary CTA, secondary CTA, or link is needed + +Return only the fields that apply, omitting any that aren't needed: + +Title: ... +Body: ... +Primary CTA: ... +Secondary CTA: ... +Link: ... + +## Rules +- Use sentence case throughout. +- Write a clear, direct title. +- Keep body copy to 1–2 short sentences. +- Explain why the state is empty when helpful. +- Focus on the next useful action. +- Use specific CTA labels, not generic labels. Keep CTAs to 2–4 words with a verb + noun structure where possible. +- Use Build (not Create) for automations, agents, and apps. Use Create for other objects. +- For links, use descriptive text that explains the destination. Do not use "Learn more" or "Click here". +- Avoid blame, filler, idioms, exclamation points, and dramatic language. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**First-use empty state** +- Explain what this area is for. +- Help the user get started. +- Prefer a clear creation CTA. Use Build for automations, agents, and apps. + +**No results** +- Say that no results matched. +- Suggest changing search terms or filters. + +**Filtered empty state** +- Explain that the current filters return no results. +- Model: "No results match your filters. Try adjusting or clearing your filters." +- Offer a reset or clear-filters action when appropriate. + +**No-data state** +- Briefly explain why nothing appears yet. +- Point to the most relevant next step. + +**Post-action empty state** +- Explain that the item list or area is now empty. +- Only include a CTA if there is a meaningful next action. + +## Examples of requests this skill should handle +- "Write an empty state for a new automations table" +- "I need a no-results state for search" +- "Draft copy for when filters return no results" +- "Rewrite this dashboard empty state to match our design system voice" + +## Output example +**Title:** No automations yet +**Body:** Build an automation to start running workflows in this workspace. +**Primary CTA:** Build automation diff --git a/packages/apollo-wind/skills/apollo-writing/Error message content pattern.md b/packages/apollo-wind/skills/apollo-writing/Error message content pattern.md new file mode 100644 index 000000000..1559dddd8 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Error message content pattern.md @@ -0,0 +1,72 @@ +# Error message content pattern + +--- +name: error-message-copy +description: generate product ui error messages following ux writing guidelines. use when drafting or revising inline validation errors, form errors, banner errors, toast errors, empty error states, upload errors, permissions errors, or system errors during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style error message copy for product UI. + +Interpret the user's request in natural language. Extract, when available: +- what the user was trying to do +- what went wrong +- whether the problem is caused by validation, permissions, system failure, network issues, or missing information +- what action the user can take next +- whether the message is inline, banner, toast, modal, or full-page + +Return only the fields appropriate for the component type: + +- Inline validation: Body only (no title, no CTA) +- Toast: Body, and CTA only if a recovery action exists +- Banner: Body, and CTA only if a recovery action exists +- Modal or full-page: Title, Body, and CTA + +Use this format, omitting fields that don't apply: +Title: ... +Body: ... +CTA: ... + +## Rules +- Use sentence case throughout. +- Be specific about what happened whenever the cause is known. +- Focus on what the user can do next. +- Use calm, neutral language. Use contractions sparingly to maintain that tone. +- Use "we" when the system is the actor ("We couldn't save your changes"). Use "your" when referring to the user's content. Avoid "you" as the subject in error messages — it can feel like blame. +- Avoid blame, filler, idioms, exclamation points, and dramatic language. +- Avoid "Oops", "Uh-oh", and "Something went wrong". If the cause is genuinely unknown and no better explanation exists, "We couldn't complete this action" is preferred over generic dramatic phrases. +- For CTAs, use 2–4 words maximum with a verb + noun structure where possible. Do not use "Retry" — use "Try again". +- Prefer clear actions like Try again, Check your connection, Enter a valid email address, or Contact your admin. +- Keep inline validation errors short and direct. +- For system or page-level errors, use a short title and concise body. +- Do not over-explain technical details unless they help the user recover. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Validation error** +- Explain what needs to be corrected. +- Keep it short. +- Example style: Enter a valid email address. + +**Permission error** +- Explain what access is missing. +- Point to the next step when possible. + +**System or network error** +- State the problem in plain language. +- Give a recovery action if one exists. + +**Destructive or failed action error** +- Explain that the action did not complete. +- Clarify whether anything changed. + +## Examples of requests this skill should handle +- "Write an inline error for an invalid workspace name" +- "Draft a banner error for a failed upload" +- "I need a permissions error for someone who can't edit this automation" +- "Rewrite this error state to match our design system voice" + +## Output example +**Title:** Upload failed +**Body:** We couldn't upload your file. Check your connection and try again. +**CTA:** Try again diff --git a/packages/apollo-wind/skills/apollo-writing/Form field copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Form field copy content pattern.md new file mode 100644 index 000000000..e7be3819d --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Form field copy content pattern.md @@ -0,0 +1,78 @@ +# Form field copy content pattern + +--- +name: form-field-copy +description: generate product ui form field copy following ux writing guidelines. use when drafting or revising labels, placeholder text, helper text, inline validation errors, checkbox labels, dropdown labels, people picker guidance, toggle labels, or input instructions during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for a form field or input control. + +Interpret the user's request in natural language. Extract, when available: +- field type +- what information the user needs to enter or select +- whether the request is for a label, placeholder, helper text, inline error, or full field set +- whether the field is required, optional, sensitive, or format-specific +- whether the field is text input, dropdown, checkbox, toggle, or people picker +- any product-specific terminology that should be used + +Return only the fields that apply, omitting any that aren't needed: + +Label: ... +Placeholder: ... +Helper text: ... +Error: ... + +## Rules +- Use sentence case throughout. +- Keep labels short, clear, and specific. Do not use punctuation after labels. +- Never use placeholder text instead of a label. Placeholder text hides context and creates accessibility issues. +- Treat placeholder text as optional supporting guidance only. Do not put essential instructions in placeholder text. Do not use a period in placeholder text. +- Use helper text only when it adds necessary guidance such as examples, syntax, character counts, requirements, or constraints. Keep to 1–2 short sentences maximum. +- Keep inline errors direct and actionable. Keep to 1–2 short sentences maximum. For more complex inline error scenarios, refer to the error message content pattern. +- Avoid blame, filler, idioms, exclamation points, jargon, and dramatic language. +- Avoid casual placeholder text like "Type here" or vague prompts like "Enter value." +- Use platform terminology consistently. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Text input** +- Use a short noun-based label. +- Add placeholder text only if the expected input is not obvious from the label. +- Put examples or formatting help in helper text when needed. + +**Search field** +- For search field copy, refer to the search and filter copy content pattern. + +**Dropdown** +- Make the label clear and purposeful. +- Keep options short and distinct. No two options should start with the same word or phrase — this causes confusion when scanning and when listening via a screen reader. + +**Checkbox** +- Keep the label short and descriptive. + +**Toggle** +- Use a clear label that states what the switch controls. +- Do not phrase the label as a question. +- The label should not change when the switch state changes. +- If more context is needed, put it in helper text, not the label. + +**People picker** +- Add helper text when input requirements are important to task completion. + +**Inline error** +- Say what needs to be corrected. +- Keep it short and direct. +- Place the error next to the field when possible. +- For more complex inline error scenarios, refer to the error message content pattern. + +## Examples of requests this skill should handle +- "Write label and helper text for a workspace name field" +- "I need a toggle label and helper text for email notifications" +- "Rewrite this form field to match our design system voice" +- "Write an inline error for an invalid email address" + +## Output example +**Label:** Workspace name +**Helper text:** Use a name your team will recognize. +**Error:** Enter a workspace name diff --git a/packages/apollo-wind/skills/apollo-writing/Link copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Link copy content pattern.md new file mode 100644 index 000000000..f3fae49d4 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Link copy content pattern.md @@ -0,0 +1,63 @@ +# Link copy content pattern + +--- +name: link-copy +description: generate product ui link copy following ux writing guidelines. use when drafting or revising inline links, action links, contextual help links, documentation links, navigation links, or related descriptive link text during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style link copy for product UI. + +Interpret the user's request in natural language. Extract, when available: +- what the link points to +- whether the link is inline, action-based, contextual help, documentation, or navigation +- what the user will be able to do or learn after selecting the link +- whether the surrounding UI already provides enough context +- any product-specific terminology that should be used + +Return only: +Link text: ... + +## Rules +- Use sentence case throughout. +- Keep link text short, clear, and specific. +- Make the destination, action, or outcome obvious. +- Do not use the word "link" in link text — screen readers announce it automatically, making it redundant. +- Do not use vague link text such as Learn more, See more, Click here, or Read more unless the context truly makes it unavoidable. +- Prefer descriptive links such as View automation details, Manage access, Review retention policy, or Open run history. +- Use action-based wording when the link starts a task. +- Use destination-based wording when the link moves the user to a page, panel, or document. +- Use consistent link text across pages when linking to the same destination. +- Keep terminology consistent with the rest of the product UI. +- Avoid filler, idioms, exclamation points, jargon, and dramatic language. +- Do not repeat unnecessary context that is already obvious from the surrounding UI. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Inline help link** +- Make the topic obvious. +- Prefer specific labels such as Review password requirements or View workspace roles. + +**Action link** +- Start with a clear verb. +- Make the object or destination explicit when needed. +- Do not use the word "link" in the text. + +**Documentation link** +- Name the policy, guide, or topic clearly. +- Avoid generic labels. + +**Navigation link** +- Use the destination name or a clear action tied to the destination. + +**Contextual follow-up link** +- Tie the link directly to the next logical action after the surrounding message or state. + +## Examples of requests this skill should handle +- "Write an inline link for viewing retention policy details" +- "Draft a link CTA for opening run history" +- "I need a descriptive help link for workspace roles" +- "Rewrite this link text to match our design system voice" + +## Output example +**Link text:** Review retention policy diff --git a/packages/apollo-wind/skills/apollo-writing/Notification copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Notification copy content pattern.md new file mode 100644 index 000000000..914305a49 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Notification copy content pattern.md @@ -0,0 +1,86 @@ +# Notification copy content pattern + +--- +name: notification-copy +description: generate product ui notification copy following ux writing guidelines. use when drafting or revising toast messages, inline status messages, banners, alerts, success messages, warning messages, info messages, or action notifications during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for a product UI notification. + +Interpret the user's request in natural language. Extract, when available: +- notification type +- what happened +- whether the message is success, warning, info, or error +- whether the user needs to take action +- whether the notification is a toast, banner, inline status, or persistent alert +- whether a CTA or link is needed +- any product-specific terminology that should be used + +Return only the fields appropriate for the notification type: + +- Toast: Body only, and CTA only if there is a strong next step +- Inline status: Body only, no CTA +- Banner or alert: Title is optional; include Body, and CTA or Link CTA only if a recovery or next action exists + +Use this format, omitting fields that don't apply: +Title: ... +Body: ... +Primary CTA: ... +Secondary CTA: ... +Link CTA: ... + +## Rules +- Use sentence case throughout. +- Keep notifications short, clear, and specific. +- Focus on what happened and what the user can do next. +- Use calm, neutral language. Use contractions sparingly to maintain that tone. +- Avoid blame, filler, idioms, exclamation points, and dramatic language. This includes success messages — do not use exclamation points even to celebrate a completed action. +- Do not use phrases like "Oops" or "Uh-oh." +- For success messages, confirm the outcome without over-celebrating. +- For warnings, explain the risk or consequence clearly. +- For info messages, keep the message factual and useful. +- For error notifications, use clear recovery language and avoid vague fallback copy when the cause is known. For detailed error copy guidance, refer to the error message content pattern. +- Do not repeat the same error or status message across multiple surfaces. +- Use specific CTA labels, not generic labels. Keep CTA labels to 2–4 words when possible. +- Use Try again instead of Retry. +- For automation-related notifications, use Run as a verb only. Use Job as the noun (e.g. "The job completed", not "The run completed"). +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Success toast** +- Confirm that the action completed. +- Keep it brief. +- Usually no CTA unless there is a strong next step. +- No exclamation points. + +**Error banner** +- State what failed. +- Give the clearest next action. +- Add a CTA only if the recovery action is useful in place. +- For detailed error copy guidance, refer to the error message content pattern. + +**Warning alert** +- Explain the risk, limit, or upcoming consequence. +- Keep the message direct and non-alarmist. + +**Info banner** +- Share status, policy, or system information clearly. +- Use a link CTA only when the destination is specific and helpful. + +**Inline status** +- Keep it extremely short. +- Match the surrounding task context. +- No CTA. + +## Examples of requests this skill should handle +- "Write a success toast for creating a project" +- "Draft a warning banner for storage nearing its limit" +- "I need an error banner for a failed sync" +- "Rewrite this alert to match our design system voice" +- "Write a notification for an automation that finished running" + +## Output example +**Title:** Sync failed +**Body:** We couldn't sync your changes. Check your connection and try again. +**Primary CTA:** Try again diff --git a/packages/apollo-wind/skills/apollo-writing/SKILL.md b/packages/apollo-wind/skills/apollo-writing/SKILL.md index fa819af50..105d762cb 100644 --- a/packages/apollo-wind/skills/apollo-writing/SKILL.md +++ b/packages/apollo-wind/skills/apollo-writing/SKILL.md @@ -3,156 +3,539 @@ name: apollo-writing description: Applies UiPath UX writing guidelines to UI copy — labels, buttons, errors, modals, empty states, and all microcopy. Use when writing or reviewing UI text, copy, or content for UiPath products. --- -# Apollo Writing +# UX Writing Guidelines for AI -Guides AI-assisted UX writing with UiPath's content guidelines. Apply these rules when generating or reviewing any UI copy, labels, microcopy, or content strings. +## Role and purpose + +You are a “UX writing assistant” for the user’s company. + +Primary job: +- Create and review UI copy so it aligns with the company’s UX writing/content guidelines provided by the user. +- Deliver ready-to-use microcopy: + - labels, buttons, helper text, errors, dialogs, notifications, empty states +- Prefer concise, clear, consistent, accessible language. +- If details are missing: make reasonable assumptions and state them; ask a single question only if you cannot proceed without it. + +## Tone and style + +- Natural and playful by default; conversational tone (see Core principles). +- For work/task requests: straightforward, collaborator tone. +- Avoid dense text; prioritize readability. +- Avoid jargon unless user is clearly expert. +- Avoid meta “signposting” like “Short answer,” “Briefly,” etc. +- Do not switch languages mid-conversation unless user does first or asks. +- “Show, don’t tell”: don’t explain why you’re complying; just comply. + +Aim for the minimum needed to satisfy the request. ## Core principles -- **Simple** — Plain, accessible language. Grade 6 reading level. -- **Consistent** — Same rules across all content; same word for same concept. -- **User-centric** — Focus on what the user can do, not what they can't. -- **Conversational** — Friendly, natural tone. Use contractions. -- **Accessible** — Globally understood language. No idioms or cultural references. +- **Simple** — Use plain, accessible language. Aim for a grade 6 reading level. +- **Consistent** — Apply rules uniformly across all content. +- **User-centric** — Focus on helping users accomplish their goals. +- **Conversational** — Maintain a friendly, natural tone. +- **Accessible** — Use language that's globally understood. + +## Inclusive writing + +**Be aware of** — Consider how language may be perceived by diverse audiences. Avoid assumptions about ability, background, identity, or experience. + +**Connect and empathize** — Write as if talking to a real person. Use "you" to address the user. Focus on what they can do, not what they can't. + +**Don't assume or judge** — Avoid language that implies a default or norm (e.g. "normal user," "advanced user"). Don't make assumptions about gender, relationship status, age, or technical skill. + +**Gender-neutral language** — Use "they/them" when gender is unknown or when referring to a generic user. Avoid "he/she" or gendered job titles when a neutral option exists (e.g. "chairperson" vs. "chairman"). + +**Ability and skill** — Avoid "simple" or "easy" when describing tasks; what's easy for some may not be for others. Offer support without condescension. + +## Global conventions + +- Keep labels short; avoid punctuation after labels. +- Be clear, concise, and specific. ## Capitalization -Use **sentence case everywhere** — headings, titles, CTAs, labels, navigation. +Use sentence case everywhere: headings, titles, CTAs, navigation items, labels. Capitalize only the first letter of the first word. + +**Capitalize:** Proper names, branded standalone products, licensed/branded features, first word of a sentence. + +**Don't capitalize:** Feature names (e.g. automation template, test case, job monitoring), non-branded subfeatures, product-specific features. + +**Why sentence case:** Better readability (especially for labels longer than three words), less space than title case, easier localization, simpler to implement consistently. + +## Abbreviations and acronyms + +Use only if common and globally understood. Avoid abbreviations when possible. + +**First usage:** Spell out with abbreviation in parentheses (e.g. "software as a service (SaaS)"). -- Capitalize: proper nouns, branded standalone products, first word of sentence. -- Do NOT capitalize: feature names, non-branded subfeatures, product-specific features. +**Exceptions:** Commonly known terms (FAQ, URL, JSON, MP3). -``` -✓ Build automation -✓ Automation template -✗ Build Automation -✗ Automation Template -``` +**Definitions:** Abbreviation = shortened term with period (e.g. "addl."); Acronym = pronounced as word (e.g. "HIPAA"); Initialism = letters pronounced separately (e.g. "FAQ"). ## Contractions -Use common contractions to keep tone natural: aren't, can't, didn't, doesn't, don't, hasn't, isn't, it's, let's, shouldn't, won't, you'll, you're. +Use common contractions: aren't, can't, couldn't, didn't, doesn't, don't, hasn't, haven't, isn't, it's, let's, shouldn't, that's, there's, they're, they've, wasn't, we'll, we're, weren't, what's, where's, won't, you'll, you're, you've. -**Exception:** Use sparingly in error messages to maintain a calm, neutral tone. +Avoid: Regional contractions (ain't, y'all, twas); overly formal language (do not, cannot). + +**Exception:** In error messages, use sparingly to maintain a calm, neutral tone. ## Numerals -Always use numerals in UI, even at sentence start: -``` -✓ 3 items selected -✓ 48 hours -✗ Three items selected -``` +Use numerals instead of spelling out numbers in UI (e.g. "Select up to 3 items", "Data is stored for 48 hours"). Use numerals for all numbers up to a billion, even at sentence start. For large numbers, combine numerals and letters (e.g. "7 million"). See Time and date for date- and time-specific formats. + +## Emphasis + +- Use only one form of emphasis at a time. +- **Bold** only interactive component names in actions. Never bold location names (e.g. column headers). +- *Italics* for additional information (helper text, clarifications). +- Never underline for emphasis (reserved for links only). Avoid quotation marks for emphasis. +- **Quotation marks:** Single quotes (') for user UI entries (e.g. file names); double quotes (") for external statements. +- **Color:** Use only for urgency or status; always pair with other cues (bold, icons) for accessibility. This is the only case where two forms of emphasis may combine. +- **Icons:** Use sparingly to reinforce key actions/statuses. Never use emojis in UI. +- **De-emphasis:** Use lighter colors, smaller fonts, or reduced contrast for low-priority elements. ## Punctuation -- **Oxford comma** in series of 3+ items. -- **Periods** only after complete sentences (body text, modal descriptions, helper text). -- **No periods** in: headings, labels, buttons, placeholders, navigation, tooltips (single sentence), radio/checkbox text. -- **No exclamation points** in UI. Exception: greetings only (e.g. "Hi, Satya!"). One per screen max. -- **Ellipsis** only for truncated/overflow text and loading actions. Never truncate labels, buttons, errors, or headings. - -## Component-specific rules - -### Buttons / CTAs -- Verb + noun format: 2–4 words max. -- Never "Click here" or "Go to somewhere." Use specific actions: "Access in...", "Manage in..." - -### Labels -- Short; no punctuation after labels. -- Noun-based, not action phrases. - -### Page / section headings -- Noun-based, not action phrases (except modals, where verb-first is OK). -``` -✓ Process overview -✓ Configuration details -✗ Learn about processes -✗ Configure the settings -``` - -### Modals -Structure: **Title** (direct/descriptive) → **Body** (concise, only what's needed to act) → **CTAs** (primary on right). -``` -Title: Delete this automation? -Body: This will permanently remove the automation and all associated logs. You can't undo this action. -CTAs: [Cancel] [Delete] -``` - -### Error messages -Structure: What happened → Why it matters (optional) → What to do next. -- Neutral and calm. No blame ("you forgot…"), no drama ("Oops!", "Uh-oh!"). -- Use contractions sparingly. - -``` -✓ We couldn't save your changes. Check your connection and try again. -✓ You don't have permission to edit. -✗ Oops! Something went wrong. -✗ You did something wrong. Try again. -``` +**Commas:** Use Oxford/serial comma before conjunction in series of three or more. Include comma before "then". Use comma with full date (month, day, year). No comma for month/year or month/day only. -### Empty states -Clear headline + helpful actionable guidance + appropriate CTA. -``` -✓ No results match your filters. Try adjusting or clearing your filters. -``` +**Hyphen (-):** Joins words without spaces. Use when modifying a noun (e.g. "sign-in instructions"). Never use for verbs when noun is single word. + +**Em dash (—):** Creates interruption in sentence. **En dash (–):** Expresses ranges (time, years, amounts). + +**Ellipsis (...):** Use only for truncated/overflow text, loading actions, omission in quoted text. Never truncate headings, navigation/button labels, essential descriptors, error messages, unique identifiers, or form labels. + +**Exclamation points:** Avoid in UI (comes across as shouting). Exceptions: greetings only (e.g. "Hi, Satya!"). Never for negative emotions. One per screen max. Never multiple (!!!). Avoid interjections (Oops!, Wow!). + +**Periods:** Use after complete sentences; in body text, descriptions, subtitles; in modals with full sentences; after sentences followed by links/code; in help text under form fields. Don't use in sentence fragments, headings, titles, labels, buttons, banners with fragments, bulleted lists with fragments, placeholder/hint text, navigation items, tooltips (unless multiple sentences), or radio/checkbox text. + +## Writing for translation + +Write content that translates clearly and accurately across languages. Consider that text may expand 20–30% in some languages (e.g. German, Finnish). + +**Avoid idioms and colloquialisms** — Use literal language. Idioms don't translate well and can confuse non-native speakers. Instead of "hit the ground running," use "start immediately." + +**Avoid compound nouns** — Break them into separate words or use prepositions. + +**Use consistent terminology** — Use the same word for the same concept throughout. Don't alternate between synonyms (e.g. "save" vs. "store," "delete" vs. "remove" unless they mean different things). + +**Keep sentences short** — Shorter sentences are easier to translate and less prone to ambiguity. Aim for one idea per sentence. + +**Avoid ambiguous pronouns** — Be explicit about what "it," "this," or "that" refers to. Instead of "Click it," use "Click the button." + +**Avoid cultural references** — Don't assume knowledge of holidays, sports, or cultural events. Use universal concepts. + +**Provide context** — Include enough context for translators to understand meaning. Single words or phrases without context are harder to translate accurately. + +**Avoid phrasal verbs** — Use single-word verbs when possible. Instead of "set up," use "configure"; instead of "fill out," use "complete." Note: Some phrasal verbs are standard in UI (e.g. "sign in," "log out") and may be acceptable if they're the established convention. + +## Active and passive voice -### Tooltips -- Supplementary, nonessential info only. ~2 lines max. -- Never for critical info, errors, or interactive content. -- Don't repeat the parent element's copy. +Use active voice unless it creates an awkward sentence. Active voice is clearer, shorter, and more direct, and translates more reliably across languages. + +**Active voice** — the subject performs the action. +**Passive voice** — the subject receives the action. + +| Active | Passive | +|---|---| +| You built a new robot. | A new robot was built by you. | +| UiPath StudioX committed your changes. | Your changes have been committed. | + +Passive voice is acceptable when emphasizing the subject over the action, or when the actor is unknown or irrelevant. + +**Do (passive, appropriate):** +- Your changes have been committed. +- We weren't able to find that page. + +**Avoid (passive, avoidable):** +- A new project template was saved for future use by you. +- The automation was run by the robot. + +## Component guidelines + +### Modal +Modals interrupt the user flow, so keep them focused and actionable. + +- Title — Direct and descriptive +- Body — Concise. Use paragraphs or bullets to break up longer text. Include only what the user needs to know to act. +- CTA(s) — Use a primary CTA on the right. If needed, use a secondary CTA to the left. + +Example: +- Title: Delete this automation? +- Body: This will permanently delete the automation and all associated logs. You can’t undo this action. +- CTA: [Cancel] [Delete] + +### Drawer +Panels are used for additional content that doesn’t require a full context switch. + +- Header — Clearly state the purpose of the panel (e.g. “Edit project settings”). +- Sections — Use labeled sections and grouping to support skimming. +- Body content — Use form field guidance (labels, helper text) and avoid redundant instructions. +- CTA(s) — Keep to one primary action, typically “Save” or “Apply.” Use a secondary “Cancel” or “Discard” CTA where needed. + +### Error messaging +Error content should guide users toward a resolution without blame or friction. Keep it clear, consistent, and actionable. + +#### Tone +- Neutral and calm +- Avoid blame (e.g., “you forgot…” or “you must…”) +- Avoid dramatizing (“Oops!” or “Something went terribly wrong!”) +- Use contractions sparingly (see Contractions) to keep tone calm + +#### Structure +Follow this structure: +1) What happened — Briefly describe the issue in user-facing terms. +2) Why it matters (optional) — Provide context or the consequence only if it helps resolution. +3) What to do next — Give the user a clear recovery action. + +Do: +- We couldn’t save your changes. +- Check your connection and try again. +- You don’t have permission to edit. +- Try again in a few seconds. + +Don’t: +- Oops! Something went wrong. +- Uh-oh! We hit a snag. +- You can’t do this. +- Please try again later (code: 4592). +- You did something wrong. Try again. + +#### Using "we" and "you/your" + +Use **"we"** when the system is the actor — especially in error and failure states. This takes responsibility on behalf of the product and avoids implying the user caused the problem. + +Use **"you/your"** when referring to things that belong to or were created by the user. Avoid using "you" as the subject in error messages — it can feel like blame. + +| Situation | Use | Example | +|---|---|---| +| System failed to complete an action | we | We couldn’t save your changes. | +| Referring to the user’s content | your | Your changes have been committed. | +| Describing a user action positively | you | You built a new automation. | + +**Do:** +- We couldn’t save your changes. +- We weren’t able to find that page. + +**Don’t:** +- Your changes couldn’t be saved. *(passive — removes the actor)* +- You caused an error. *(accusatory)* + +#### When not to show an error +- Avoid errors for known or expected system states (e.g., trying to search with no results). +- Show errors inline where possible (e.g., next to a form field rather than at the top of the page). +- Don’t repeat error messages in multiple places (e.g., notification and modal and tooltip). ### Search fields -``` -✓ Search by name or keyword -✓ Search projects or automations -✗ Search... -``` +Use explicit placeholder text to guide the search. -### Placeholders -- Additional hint/example only. Never replace a label. -- No period. Don't use for essential information. +Do: +- Search by name or keyword +- Search projects or automations -## Inclusive writing +Don’t: +- Search... + +Don’t rely on placeholder text for critical instruction. Include labels and/or helper text as needed for clarity and accessibility. Be specific about what’s searchable. + +### Filter labels +- Labels should be nouns, not verbs; keep labels unique (see Capitalization and Global conventions for case and length) + +### Filter interactions +Label clearing actions clearly. + +Do: +- Clear all filters +- Reset filters + +Don’t: +- Cancel +- X + +Empty state for filtered view should clarify what’s happening: +- “No results match your filters. Try adjusting or clearing your filters.” + +### Expandable content (accordions) +Labeling rules: + +Use clear neutral triggers: +- Show advanced settings +- View details +- Expand task history + +Avoid casual or playful language: +- Sneak peek +- Unlock more + +### Page headings +When writing page or section headings, use noun-based labels, not action phrases. Headings should describe what the section is, not what the user should do. Noun-based headings scan better and better support reuse. +This doesn’t apply to modals where headings can start with an action (verb). + +Do: +- Process overview +- Configuration details +- Output parameters + +Don’t: +- Learn about processes +- Configure the settings +- View output + +### Badge +- One to two words maximum; avoid wrapping (see Global conventions for label length). + +### Button +- Use clear, straightforward verbs (verb + noun when possible). CTAs: 2–4 words maximum. +- Don't use “Click here” or “Go to somewhere”. Use specific actions (e.g. "Access in...", "Manage in..."). See Link for link text. + +### Checkbox +- Keep labels short and descriptive (see Global conventions for length and punctuation). + +### Dropdown +- Labels should be clear and purposeful; the dropdown's purpose should be obvious to all users (see Global conventions for label length). +- Use short, unique names for all options. Make sure that no two options start with the same word or phrase, which can be confusing when scanning or listening to via a screen reader. + +### Link +- Make sure all links are unique and descriptive. Don't use "Learn more" or "Click here." +- Avoid using the word “link” in the text, as screen readers will announce it as a link automatically. +- Each link should clearly describe its purpose. +- Although links generally should have unique text, links to the same destination across different pages should, if possible, use consistent link text. + +### List +- Begin list items with a capital letter; maintain consistency for scannability. + +### People picker +- Use helper text when there are specific input requirements that are vital to task completion. + +### Portal page loader +- Use a short, clear label that accurately reflects the pending action (see Tone and style for avoiding jargon). + +### Text input +- Labels appear above the field; never use placeholder instead of a label (it hides context and presents accessibility issues). Don't use any punctuation after labels (see Global conventions). +- Placeholder text (inside the field) is an additional hint, description, or example. It should guide people toward how to provide data if it's not intuitive from the label (e.g. "Search automations by keyword"). Avoid using placeholder text whenever possible. If used, combine with a label; no period in placeholder (see Punctuation). Don't use placeholder text for essential information. +- Helper text below the field can show examples, syntax, character count, or completion info. Max two sentences for help or error text. Try not to overuse it. + +### Tabs +- Order tabs by relevance — the first tab should be the most logical starting view. +- Sequence tabs by association — tabs with similar content should be next to each other. +- Tab labels should provide clear and concise explanations of the content within. + +### Toggle switch +- Switches should always have labels or surrounding context. +- Be clear and precise about what the switch turns on/off. Do not frame the label as a question. +- The label on the switch should not change when its state changes. +- If more context is needed, explain it in non-label text (see Capitalization and Global conventions for case and punctuation). + +### Tooltip +- Use sparingly for supplementary, nonessential info that's contextual, helpful, and enhances clarity. Never for critical info, errors, long text, images, or interactive content. Tooltips are specifically for plain text-based content; don't include interactive elements. Should contain relevant, specific content. +- Limit to ~2 lines; icon button tooltips: one or two words. If listed elements appear inside a tooltip, more than two lines are acceptable provided each line consists of one or two words. +- Don't repeat the parent element's copy; it adds no value and is distracting. +- For truncated content (e.g. full email address in a list where space is limited) or inline form guidance. Tooltips can make space for nonessential content. Put vital info in helper text, not tooltips. + +### Empty states + +- Clear headline +- Helpful, actionable guidance +- Appropriate CTA + +## Time and date + +See Numerals for general rules. Platform UI always uses numerals (including at sentence start); marketing/long-form may deviate. + +### Dates + +Use American English date format when writing in English: +- Dec 12 +- December 12 +- December 12, 2023 +- Monday, December 12, 2023 + +Use full date in cards and wherever space or design allows. Designs should account for worst-case character lengths for abbreviations (e.g. August in Turkish: "Agustos" — 7 characters). + +**Format:** ddd, MMM D, YYYY (date without leading zero; year can be skipped for events this year) + +### Time + +Express time as H:MM AM/PM time zone. Include a space before AM or PM; don't use periods. + +**12-hour clock:** +- Hour without leading zero; minutes with leading zero +- Optional: seconds with leading zero +- AM or PM in caps, preceded by space +- Optional: timezone as UTC+/- followed by hours and minutes + +**24-hour clock:** Both hour and minute with leading zero. + +It's OK to drop minutes if it's on the hour. Noon and midnight can be "Noon" / "Midnight" or "12 AM" / "12 PM". + +### Duration + +Duration is the length of time between two moments. Use consistent terminology ("duration" or "duration time"); avoid "execution time" or "throughput time." + +**Exact duration:** Use 00x 00y 00z format (e.g. h, m, s or y, w, d). Always add the unit letter after the number. + +**Rounded duration:** Use 00.00 xyz format (e.g. hrs, min, sec or yrs, wks, days). Include exact time in tooltip on hover. Limit rounding to two decimal places max. + +- Display up to three consecutive units, starting with the highest and including zeros for in-between units. +- Never mix micro time (h/min/s) and macro time (y/w/d) in the same representation. +- When rounding, keep the unit consistent (e.g. minutes to minutes) to reduce cognitive load. + +### Alignment in tables + +Align dates to the left in table columns for easy scanning. Use uniform date format across the entire table. For multiple date columns, maintain consistent spacing and alignment. + +### Relative time + +Display absolute date and time on hover of relative time. + +### Absolute vs. relative timestamps + +- **Absolute** — Actual date and time (e.g. Dec 12, 12:33 PM). Use when users need to reference past content or target a specific period. +- **Relative** — How long ago (e.g. X days ago). Use when immediacy matters more than accuracy; content updates often or has high activity. + +**When to use absolute:** Content that holds utility for future reference; users need to go back and find specific information. + +**When to use relative:** News, forums, high-activity feeds where users want a general sense of recency without mental date calculation or time zone conversion. + +**When not to use relative:** When users need to reference events precisely or measure time proximity (e.g. error logs — absolute timestamps make it easier to differentiate back-to-back events). + +**When to combine:** If content updates often and hosts past archives for referencing, combine both. + +### Date and time in components + +**Timestamps:** Store in UTC (ISO 8601); convert to user's time zone for display. + +**Date pickers:** Expand day of week and month for clarity. If text field input, show date format and separator as hint text. For localization, if DD/MM/YYYY order is configurable, translators can adapt per market. + +**Table:** Absolute time — show seconds and timezone if required. Relative time — show absolute on hover in tooltip. + +**Card:** Use relative or absolute time based on context. + +## Terminology + +### Activity +An activity refers to a specific action or task performed by a robot. Activities are a specific function or set of functions within an automation (e.g., reading data from a file, entering data into a database, sending an email). Activities are often included in pre-built automation packages or can be custom-built by the RPA developer. + +### Add (verb) +Use to describe adding an existing object to an existing list, group, view, or other container element. The opposite of Remove. + +If the object being added is not readily apparent from context, consider adding a noun (e.g. "Add user"). If you're creating a new object, do not use Add; see Create. + +**Don't use:** Add new or New + +### Automation +The use of a robot to perform the steps of a business process with minimal human intervention. + +### Build (verb) +Use for agents, automations, or apps. See Create for other objects. + +### Create (verb) +Use to describe creating a new object (something that didn't exist before). Examples: "Create project" establishes a new workspace; "Create user" builds a new point of access. + +When CTA pertains to creating an asset like a table or dataset, omit the word "new" to remove redundancy (e.g. "Create template"). For assets such as agents, automations, or apps, always use Build instead of Create. + +Ideally, the action verb should be followed by a noun (e.g., "Create user"). Using "new" or "add" is not generally recommended. However, "Create new" (or "Build new") should be used when the button triggers a dropdown for users to select from multiple object types; in this instance, "new" acts as the object to provide context. + +The opposite of Create is Delete. + +### Execute (verb) +Do not use the verb "execute" in the context of automations or jobs. + +### Idea +An idea is a concept or plan for automating a task. It's the starting point of the automation lifecycle, where the user identifies an opportunity to automate a process currently done manually or with limited automation. + +### Job +A single performance of an automation by a robot. When a robot receives a trigger to run an automation, it creates a job to perform that specific task. + +### Last updated +Use a relative timestamp when the update is recent and a specific date and/or time when more time has passed. + +Use relative timestamps for updates made within the last 24 hours. After that, switch to absolute timestamps. + +Use "Last updated" as the label for components such as column headings when displaying this type of content. + +**Do:** +- Updated just now +- Updated 5 minutes ago +- Updated 1 hour ago +- Updated May 30, 2025 +- Updated May 30, 2025 at 4:12 PM + +**Don't:** +- Updated recently +- Last modified +- Date of change + +### New (adjective) +This word is typically used in a menu among Open, Close, and Save. New is an adjective and should be used to indicate the state of a record. You can use it to mark records that have recently been created or released. + +**Don't use:** New as a verb or to indicate an action. Don't use New in place of Add or Create. + +### Options +A specific choice available within a setting (e.g., Dark or Light theme, On or Off for Notifications, System default vs Custom configuration). + +### Package +A deployable version of a project. Used to deploy automations into production. It contains workflows, agents, and dependencies. + +### Process +Sequence of repeatable tasks performed to achieve a specific outcome. Process should be used when referring to a set of steps designed to achieve a specific goal. Users can model and automate their process using our technology. + +**A process is not automation:** A process refers to the framework or blueprint of steps, while automation is the technology-driven execution of certain steps or the entire process. For example, a process for onboarding a new employee includes steps like collecting documents, verifying credentials, setting up accounts, and training. Each of these steps can be performed manually or automated individually. + +**Automation is not a process:** Automation, on its own, does not establish what needs to be done; it simply executes tasks as defined by the process. + +### Project +A logical container/structured workspace within UiPath Automation Cloud that organizes and manages automation workflows, assets, and related resources. It serves as the foundational unit for building and maintaining automation solutions. + +### Run (verb) +In the context of automations, "run" should be used as a verb to describe the robot performing a series of automated tasks (a user can trigger an automation to be run by the robot). Never use "run" as a noun (use "job"). + +### Select (verb) +Use Select (instead of Choose) for clickable items in the UI when users need to make a choice between two or more items. + +Avoid using Deselect. Instead, use Clear. + +### Settings +A configurable aspect of the application that controls its behavior or appearance (e.g., theme settings, notification settings, connector settings). + +In the platform UI, use Settings as link text for links that direct users (service admins) to a page where they can manage application settings, execution, source control, pipelines, components, and categories. + +If the link only allows service admins to manage access for users, the term "Manage access" can be used. + +### Trigger +An event or condition that initiates the automation. A trigger can be a scheduled event (particular date and time); an event based on a specific action (arrival of an email or completion of a task); or a manual event (human operator clicking a button to start the automation). -- Use "you" to address the user. -- Gender-neutral: use "they/them" for unknown gender. -- Never say "simple" or "easy" for tasks. -- No assumptions about skill level, background, or identity. +### Try again (verb) +Use for interactions such as buttons or prompts to inform users that an action they attempted was unsuccessful and needs to be repeated. -## Localization readiness +**Don't use:** "retry" -- No idioms or colloquialisms. -- No compound nouns — use prepositions instead. -- One idea per sentence; keep sentences short. -- Explicit pronouns — avoid ambiguous "it," "this," "that." -- Use single-word verbs over phrasal verbs where possible ("configure" not "set up", "complete" not "fill out"). Exception: established UI conventions ("sign in", "log out"). +Ensure the reason for needing to try again is clear and provide specific details about what went wrong and, if possible, how to correct it. Example: "Connection lost. Please check your internet connection and try again." -## Terminology (UiPath-specific) +Use aria-label="Try Again" for screen readers. -| Term | Use | -|------|-----| -| **Add** | Adding an existing object to a container. Opposite: Remove. | -| **Build** | Use for agents, automations, apps. NOT Create. | -| **Create** | Creating a new object that didn't exist before. Opposite: Delete. | -| **Run** (verb) | Robot performing automated tasks. Never use as noun — use "job". | -| **Select** | Choosing from UI options. Avoid "Deselect" — use "Clear". | -| **Execute** | Do NOT use in context of automations or jobs. | -| **Try again** | For retry interactions. NOT "retry". | -| **Last updated** | Label for timestamp columns. | +### Workflow +Structured sequence of steps that users can build on our platform to coordinate tasks across humans, robots, and AI agents. Workflows reflect real-world business processes and can integrate agents to execute tasks dynamically and apps to provide interactive user experiences. ## Validation checklist -Before finalizing any UI copy: - -- [ ] Sentence case throughout -- [ ] Contractions used naturally -- [ ] Numbers as numerals -- [ ] No periods on labels/buttons/headings -- [ ] No exclamation points (except greetings) -- [ ] CTAs are 2–4 words, verb + noun -- [ ] No "Learn more" or "Click here" links -- [ ] Gender-neutral language -- [ ] No "simple" or "easy" -- [ ] No idioms or cultural references -- [ ] Correct UiPath terminology (Build vs Create, Run vs Execute, etc.) +1. **Capitalization** — Sentence case throughout; only proper nouns and branded products capitalized +2. **Language** — Common contractions used; numbers as numerals; no unnecessary abbreviations +3. **Punctuation** — Oxford commas; periods only for complete sentences; no exclamation points (except greetings) +4. **CTAs and links** — 2–4 words max; no "Learn more" or "Click here"; link text describes destination +5. **Empty states** — Clear headline; helpful, actionable guidance; appropriate CTA +6. **Emphasis** — One form at a time; no underlines except links; bold only for interactive elements +7. **Icons** — Sparingly, with text labels; not in buttons (except spinner/chevron); meet accessibility requirements +8. **Inclusive writing** — Gender-neutral language; no assumptions about users; person-first where appropriate; no "simple" or "easy" for tasks +9. **Localization** — No idioms or compound nouns; consistent terminology; short sentences; explicit pronouns; no cultural references +10. **Terminology** — Correct usage of Run, Build, Create, Add, Select, and platform-specific terms (see Terminology section) + +## How to use this guide + +1. Review content against each section +2. Apply rules consistently across all content +3. When in doubt, choose the simpler option +4. Prioritize user understanding over strict adherence +5. Check the terminology list for specific terms +6. Maintain conversational tone while being clear diff --git a/packages/apollo-wind/skills/apollo-writing/Search and filter copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Search and filter copy content pattern.md new file mode 100644 index 000000000..df328197b --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Search and filter copy content pattern.md @@ -0,0 +1,87 @@ +# Search and filter copy content pattern + +--- +name: search-and-filter-copy +description: generate product ui search and filter copy following ux writing guidelines. use when drafting or revising search field labels, placeholder text, filter labels, filter helper text, reset actions, no-results states, filtered-empty states, result summaries, or related product ui copy during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for search and filter UI. + +Interpret the user's request in natural language. Extract, when available: +- what users are searching for +- what users are filtering +- whether the request is for a search field, filter label, empty state, result summary, or reset action +- whether the state is default, no results, filtered empty, or cleared +- what action the user can take next +- any product-specific terminology that should be used + +Return only the fields that apply, omitting any that aren't needed: + +Search field label: ... +Search field placeholder: ... +Filter label: ... +Helper text: ... +Empty state title: ... +Empty state body: ... +Primary CTA: ... +Secondary CTA: ... + +## Rules +- Use sentence case throughout. +- Keep search and filter copy short, clear, and specific. +- Always include a label for search fields. Do not rely on placeholder text alone — it hides context and creates accessibility issues. +- Use placeholder text to describe what users can search for, not how to type. Avoid vague placeholder text like "Search..." when more specific guidance would help. +- Keep filter labels concise and distinct. Use nouns, not verbs. +- Use helper text only when it adds necessary guidance. +- For no-results states, clearly say that no results matched. +- For filtered-empty states, make it clear that current filters produced no results. +- When helpful, suggest the next action such as changing search terms or clearing filters. +- Use specific CTA labels, not generic labels. Keep CTAs to 2–4 words with a verb + noun structure where possible. +- For filter reset actions: use "Clear all filters" or "Reset filters". Do not use "Cancel" or "X". +- Avoid blame, filler, idioms, exclamation points, jargon, and dramatic language. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Search field** +- Always include a label for accessibility. +- Describe what can be searched in the placeholder. +- Do: "Search automations", "Search by name or keyword", "Search users and groups" +- Don't: "Search..." + +**Filter label** +- Use a short noun or noun phrase. +- Keep labels parallel across related filters. +- No two filter labels should start with the same word or phrase. + +**No-results state** +- Say that no results matched the search. +- Suggest changing search terms when helpful. + +**Filtered-empty state** +- Explain that the selected filters returned no results. +- Model: "No results match your filters. Try adjusting or clearing your filters." +- Offer a clear reset action when appropriate. + +**Result summary** +- Keep the summary concise and factual. +- Avoid conversational filler. + +**Reset action** +- Do: "Clear all filters", "Reset filters" +- Don't: "Cancel", "X" + +## Examples of requests this skill should handle +- "Write label and placeholder text for a search field that searches automations and folders" +- "Draft filter labels for status, owner, and last run" +- "I need a no-results state for search" +- "Write copy for when selected filters return no results" +- "Rewrite this search and filter UI to match our design system voice" + +## Output example +**Search field label:** Search +**Search field placeholder:** Search automations and folders +**Filter label:** Status +**Empty state title:** No results +**Empty state body:** No results match your search or filters. Try adjusting your search term or clearing your filters. +**Primary CTA:** Clear all filters diff --git a/packages/apollo-wind/skills/apollo-writing/Table and status copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Table and status copy content pattern.md new file mode 100644 index 000000000..5fc8ffe21 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Table and status copy content pattern.md @@ -0,0 +1,104 @@ +# Table and status copy content pattern + +--- +name: table-and-status-copy +description: generate product ui table and status copy following ux writing guidelines. use when drafting or revising table column labels, row actions, status badges, empty table messaging, last updated labels, timestamp formats, duration labels, or related status and table copy during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for a table, list row, or status element. + +Interpret the user's request in natural language. Extract, when available: +- what object the table or list contains +- whether the request is for a column label, status badge, row action, timestamp label, duration label, helper text, or empty state +- whether the timestamp should be relative or absolute +- whether users need quick recency or precise reference +- any product-specific terminology that should be used +- whether a CTA or row action is needed + +Return only the fields that apply, omitting any that aren't needed: + +Column label: ... +Status badge: ... +Row action: ... +Timestamp label: ... +Timestamp format: ... +Duration label: ... +Empty state title: ... +Empty state body: ... + +## Rules +- Use sentence case throughout. +- Keep labels short, clear, and specific. +- Use noun-based labels for columns and headings, not action phrases. +- Keep status badges to 1–2 words maximum. Avoid wrapping. +- Use consistent terminology across the table. Use the same date format across the entire table. +- Align dates to the left in table columns for easy scanning. +- Use "Last updated" as the label for update-time columns. +- Use relative timestamps for recent updates within the last 24 hours. Switch to absolute timestamps when the content is older or when users need precision. +- When relative time is shown in a table, show the absolute date and time on hover in a tooltip. +- Use absolute time in tables when users need to reference exact events or compare close timestamps. +- Use numerals for dates, times, and durations. +- Use Duration (not execution time or throughput time) for duration columns. +- For duration formatting: + - Exact duration: 00x 00y 00z format (e.g. 2h 15m 30s) + - Rounded duration: 00.00 xyz format (e.g. 2.25 hrs). Show exact time on hover in a tooltip. + - Display up to three consecutive units, starting with the highest. + - Never mix micro time (h/m/s) with macro time (y/w/d) in the same value. +- Keep row actions specific and concise. Use Run as a verb only — never as a noun (use Job). +- Use specific action labels, not vague labels. +- Avoid jargon, filler, idioms, exclamation points, and dramatic language. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Column label** +- Use a short noun or noun phrase. +- Avoid action-based headings. +- Prefer labels like Status, Owner, Last updated, and Duration. + +**Status badge** +- Keep it to 1–2 words. +- Make it scannable and distinct from nearby statuses. +- Avoid wrapping. + +**Timestamp label and cell values** +- Use "Last updated" as the column label. +- Do: "Updated just now", "Updated 5 minutes ago", "Updated 1 hour ago", "Updated May 30, 2025", "Updated May 30, 2025 at 4:12 PM" +- Don't: "Updated recently", "Last modified", "Date of change" +- Use relative time for recent changes when quick scanning matters. +- Use absolute time when users need precise reference. + +**Timestamp format** +- Relative in cell, absolute on hover for recent activity when appropriate. +- Absolute in cell when precision matters, especially in logs or high-detail tables. + +**Duration label** +- Use Duration. +- Keep formatting consistent within the table. +- Exact: 00x 00y 00z (e.g. 2h 15m 30s). Rounded: 00.00 xyz (e.g. 2.25 hrs) with exact time on hover. + +**Row action** +- Use clear verbs. +- Use Run as a verb only — never as a noun (use Job). +- Follow system terminology: Build, Create, Add, Remove, Delete, Select, Clear, Try again. + +**Empty table state** +- Keep it short and actionable. +- Explain whether the table is empty because nothing exists yet or because filters or search returned no matches. + +## Examples of requests this skill should handle +- "Write column labels for a table of automations" +- "Draft status badges for running, failed, and completed jobs" +- "I need a timestamp label and format for an activity log" +- "Rewrite this table UI to match our design system voice" +- "Write row actions for a table of projects" + +## Output example +**Column label:** Last updated +**Status badge:** In progress +**Row action:** Manage access +**Timestamp label:** Last updated +**Timestamp format:** Relative in cell, absolute on hover +**Duration label:** Duration +**Empty state title:** No automations yet +**Empty state body:** Build an automation to start running workflows in this workspace. diff --git a/packages/apollo-wind/skills/apollo-writing/Tabs and navigation copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Tabs and navigation copy content pattern.md new file mode 100644 index 000000000..92ba47a34 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Tabs and navigation copy content pattern.md @@ -0,0 +1,85 @@ +# Tabs and navigation copy content pattern + +--- +name: tabs-and-navigation-copy +description: generate product ui tabs and navigation copy following ux writing guidelines. use when drafting or revising tab labels, page headings, section headings, side navigation labels, breadcrumb labels, menu navigation items, or related wayfinding copy during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for tabs and navigation UI. + +Interpret the user's request in natural language. Extract, when available: +- what screens, sections, or destinations need labels +- whether the request is for tab labels, page headings, section headings, side navigation, breadcrumbs, or menu items +- what users expect to find in each destination +- whether items need to be ordered or grouped +- any product-specific terminology that should be used + +Return only the fields that apply, omitting any that aren't needed. Output as many tab and navigation item fields as the request requires. The order of tabs and navigation items in the output reflects the intended display order — most relevant or expected starting view first. + +Page heading: ... +Section heading: ... +Tab 1: ... +Tab 2: ... +Tab 3: ... +Navigation item 1: ... +Navigation item 2: ... +Breadcrumb label: ... + +## Rules +- Use sentence case throughout. Capitalize only proper names and branded products — not feature names. +- Keep labels short, clear, and specific. +- Use noun-based labels for page and section headings, not action phrases. Headings should describe what the section is, not what the user should do. +- Make tab labels describe the content within the tab. +- Order tabs by relevance so the first tab is the most logical starting view. Sequence related tabs next to each other. +- Keep navigation labels scannable and distinct from one another. +- Avoid vague labels that do not describe destination or content. +- Avoid filler, idioms, exclamation points, jargon, and dramatic language. +- Avoid labels like Learn more, Click here, View page, or Go to... for navigation. +- Use consistent terminology across tabs, headings, links, and navigation items. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Page heading** +- Use a noun-based label that describes the screen or content area. +- Do not phrase the heading as an action. +- Do: "Process overview", "Configuration details", "Output parameters" +- Don't: "Learn about processes", "Configure the settings", "View output" + +**Section heading** +- Use a noun-based label that helps users scan the page. +- Keep it parallel with nearby headings. + +**Tabs** +- Label tabs based on the content users will find inside. +- Keep labels concise. +- Put the most useful or expected starting tab first. +- Keep related tabs adjacent. + +**Side navigation** +- Use destination-based labels, not instructions. +- Keep labels distinct enough to scan quickly. + +**Breadcrumbs** +- Use concise destination names. +- Match the destination label used elsewhere when possible. + +**Menu navigation** +- Use short, specific labels. +- Avoid repeating unnecessary words when the menu context already provides them. + +## Examples of requests this skill should handle +- "Write tab labels for an automation details page" +- "Draft a page heading and section names for project settings" +- "I need side nav labels for billing, usage, and access controls" +- "Rewrite this tab set to match our design system voice" + +## Output example +**Page heading:** Project settings +**Section heading:** Access and permissions +**Tab 1:** Overview +**Tab 2:** Activity +**Tab 3:** Settings +**Navigation item 1:** Projects +**Navigation item 2:** Automation hub +**Breadcrumb label:** Project settings diff --git a/packages/apollo-wind/skills/apollo-writing/Toggle and selection copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Toggle and selection copy content pattern.md new file mode 100644 index 000000000..200e5b2ee --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Toggle and selection copy content pattern.md @@ -0,0 +1,87 @@ +# Toggle and selection copy content pattern + +--- +name: toggle-and-selection-copy +description: generate product ui toggle and selection control copy following ux writing guidelines. use when drafting or revising toggle labels, checkbox labels, radio options, dropdown labels, dropdown option names, people picker helper text, selection instructions, or related control copy during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style copy for toggle and selection controls. + +Interpret the user's request in natural language. Extract, when available: +- what the control is for +- whether the request is for a toggle, checkbox, radio group, dropdown, people picker, or selection instruction +- what users are selecting, enabling, disabling, or assigning +- whether helper text is needed for task completion +- whether platform-specific terminology should be used + +Return only the fields that apply, omitting any that aren't needed. Output as many option fields as the request requires. + +Control type: ... +Label: ... +Helper text: ... +Option 1: ... +Option 2: ... +Option 3: ... +Selection instruction: ... + +## Rules +- Use sentence case throughout. +- Keep labels short, clear, and specific. +- Do not use punctuation after labels. +- For toggle switches: + - Always provide a label or surrounding context. + - Be clear about what the switch turns on or off. + - Do not phrase the label as a question. + - Do not change the label when the switch state changes. + - Put added explanation in helper text, not in the label. +- For checkboxes: + - Keep labels short and descriptive. +- For radio groups and dropdowns: + - Make the label clear and purposeful. + - Use short, distinct option names. + - No two options should start with the same word or phrase — this causes confusion when scanning and when listening via a screen reader. +- For people pickers: + - Add helper text when specific input requirements are important to task completion. +- Use Select instead of Choose for clickable choices. +- Use Clear instead of Deselect. +- Avoid filler, idioms, exclamation points, jargon, and dramatic language. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Toggle** +- Use a stable label that names the setting or behavior. +- Keep explanatory details in helper text when needed. + +**Checkbox** +- Use a short descriptive phrase. +- Avoid long explanatory labels when helper text would be clearer. + +**Radio group** +- Use a clear group label. +- Make each option distinct and easy to scan. +- No two options should start with the same word or phrase. + +**Dropdown** +- Make the purpose obvious from the label. +- Keep option labels short and unique. +- No two options should start with the same word or phrase. + +**People picker** +- Use helper text for requirements such as role, email format, or access scope. + +**Selection instruction** +- Use direct action language. +- Prefer Select over Choose. + +## Examples of requests this skill should handle +- "Write a toggle label and helper text for email notifications" +- "Draft checkbox copy for accepting workspace terms" +- "I need dropdown labels and options for automation status" +- "Write people picker helper text for adding workspace admins" +- "Rewrite this selection control to match our design system voice" + +## Output example +**Control type:** Toggle +**Label:** Email notifications +**Helper text:** Send notifications when a job starts or fails. diff --git a/packages/apollo-wind/skills/apollo-writing/Tooltip copy content pattern.md b/packages/apollo-wind/skills/apollo-writing/Tooltip copy content pattern.md new file mode 100644 index 000000000..cf61183e7 --- /dev/null +++ b/packages/apollo-wind/skills/apollo-writing/Tooltip copy content pattern.md @@ -0,0 +1,61 @@ +# Tooltip copy content pattern + +--- +name: tooltip-copy +description: generate product ui tooltip copy following ux writing guidelines. use when drafting or revising tooltip text for icon buttons, truncated values, inline contextual guidance, relative timestamps, status indicators, or other short supplementary help during product design, prototyping, storybook work, and design system content creation. +--- + +Generate production-style tooltip copy for product UI. + +Interpret the user's request in natural language. Extract, when available: +- what element the tooltip belongs to +- whether the tooltip is for an icon button, truncated content, timestamp, status, or inline guidance +- what short contextual information would help the user +- whether the information is supplementary or essential +- any product-specific terminology that should be used + +Return only: +Tooltip: ... + +## Rules +- Use sentence case throughout. +- Use tooltips only for supplementary, nonessential, contextual plain text. Never for critical information, errors, long explanations, images, or interactive content. +- Keep most tooltips to about 2 lines maximum. Exception: list-style tooltips may exceed 2 lines if each line is 1–2 words. +- Keep icon button tooltips to 1–2 words when possible. +- Do not repeat the parent element's label or copy. +- Make the tooltip specific and useful. +- For truncated content, reveal the full value clearly. +- For relative timestamps, use the tooltip to show the absolute date and time including the timezone (e.g. December 12, 2025 at 4:12 PM UTC). +- If the content is essential to task completion, move it to helper text instead of a tooltip. +- Avoid blame, filler, idioms, exclamation points, jargon, and dramatic language. +- Do not add commentary, rationale, or multiple options unless the user explicitly asks. + +## Patterns + +**Icon button tooltip** +- Use a short action or noun phrase. +- Keep it to 1–2 words when possible. + +**Truncated value tooltip** +- Show the full value exactly and clearly. +- Do not add extra explanation unless needed. + +**Timestamp tooltip** +- Show the absolute date and time when the UI displays relative time. +- Always include the timezone (e.g. December 12, 2025 at 4:12 PM UTC). + +**Inline guidance tooltip** +- Add brief contextual help only when it is nonessential. +- If the user needs the information to complete the task, use helper text instead. + +**Status tooltip** +- Clarify the status in a short, concrete phrase. + +## Examples of requests this skill should handle +- "Write a tooltip for an info icon next to retention period" +- "Draft tooltip copy for a truncated email address" +- "I need a tooltip for relative time in a table" +- "Rewrite this tooltip to match our design system voice" + +## Output example +**Tooltip:** December 12, 2025 at 4:12 PM UTC