npm - imhcode - Versions diffs - 1.0.0 - Mend

imhcode 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (986) hide show

package/skills/design-auditor/references/i18n.md ADDED Viewed

@@ -0,0 +1,254 @@
+# Internationalization (i18n) & RTL Reference
+Internationalization is building a product that can be adapted for different languages and regions without engineering changes. Localization (l10n) is the actual adaptation for a specific locale.
+This reference focuses on what's visible in the design — the things that break or look wrong when a product goes multilingual.
+---
+## Text Expansion
+Different languages take up very different amounts of space than English. This is the most common i18n design failure.
+### Typical Expansion Rates vs English
+| Language | Expansion |
+|---|---|
+| German | +30–40% |
+| Finnish | +30–40% |
+| French | +15–25% |
+| Spanish | +15–25% |
+| Portuguese | +15–30% |
+| Russian | +15–25% |
+| Arabic | -20–25% (shorter but RTL) |
+| Chinese/Japanese/Korean | -30–50% (denser characters) |
+### How to Design for Text Expansion
+**Buttons:**
+- Don't use fixed-width buttons. Use `min-width` with horizontal padding, so the button grows with the text.
+- Test with a German or Finnish string — if the button wraps or overflows, the design isn't ready.
+- Avoid putting two buttons side by side in a tight space — one may grow and overlap the other.
+**Navigation:**
+- Horizontal nav bars are the most vulnerable — they clip or wrap when labels expand.
+- Test nav items with longer strings. Consider icon-only nav on mobile, with labels on desktop.
+**Labels & headings:**
+- Truncation (`text-overflow: ellipsis`) is acceptable for secondary content, never for critical labels.
+- Two-line truncation is safer than one-line for headings.
+**Cards & table cells:**
+- Fixed-height cards clip translated text. Use `min-height` not `height`.
+- Table cells should allow text wrapping, not fixed heights.
+### Testing for Expansion
+The quickest test: temporarily replace all strings with a string 40% longer than the original and scan for breakage.
+---
+## RTL (Right-to-Left) Languages
+RTL languages: **Arabic, Hebrew, Persian (Farsi), Urdu, Pashto, Sindhi**
+In RTL, the entire reading direction reverses — and the UI layout should mirror accordingly.
+### What Mirrors in RTL
+| Element | LTR | RTL |
+|---|---|---|
+| Text alignment | Left | Right |
+| Page layout direction | Left to right | Right to left |
+| Navigation | Logo left, actions right | Logo right, actions left |
+| Sidebar | Left | Right |
+| Form fields | Left-aligned | Right-aligned |
+| Progress bars | Fill left → right | Fill right → left |
+| Breadcrumbs | Home > Section > Page | Page < Section < Home |
+| List bullets/numbers | Left of text | Right of text |
+| Tooltips | Open right | Open left |
+| Scrollbar | Right side | Left side |
+| Back button icon | ← | → |
+### What Does NOT Mirror in RTL
+| Element | Stays the Same |
+|---|---|
+| Clock direction | Always clockwise |
+| Phone numbers | Always LTR |
+| Prices / currencies | Depends on locale standard |
+| Code snippets | Always LTR |
+| Non-directional icons | Heart, star, trash, settings |
+| Media controls | Play/pause buttons stay the same |
+| Logos | Unless specifically designed with RTL version |
+| Mathematical expressions | Always LTR |
+### Implementing RTL in Code
+**HTML level:**
+```html
+<html dir="rtl" lang="ar">
+```
+Or per section:
+```html
+<div dir="rtl">...</div>
+```
+**CSS — Use logical properties instead of directional ones:**
+| ❌ Directional (breaks in RTL) | ✅ Logical (works in both) |
+|---|---|
+| `margin-left` | `margin-inline-start` |
+| `margin-right` | `margin-inline-end` |
+| `padding-left` | `padding-inline-start` |
+| `padding-right` | `padding-inline-end` |
+| `border-left` | `border-inline-start` |
+| `left: 0` | `inset-inline-start: 0` |
+| `text-align: left` | `text-align: start` |
+| `text-align: right` | `text-align: end` |
+| `float: left` | `float: inline-start` |
+**CSS `transform` for directional icons:**
+```css
+/* Flip directional icons in RTL */
+[dir="rtl"] .icon-arrow,
+[dir="rtl"] .icon-chevron,
+[dir="rtl"] .icon-back {
+  transform: scaleX(-1);
+}
+```
+### RTL-Specific Design Checklist
+- [ ] `dir="rtl"` applied at html or section level
+- [ ] CSS uses logical properties (`inline-start/end`) not directional (`left/right`)
+- [ ] Directional icons (arrows, chevrons) flip in RTL
+- [ ] Layout mirrors (sidebar, nav, cards)
+- [ ] Progress bars and sliders fill from correct direction
+- [ ] Form fields are right-aligned
+- [ ] Text is right-aligned
+- [ ] Scrollbar moves to left side (handled by browser with `dir="rtl"`)
+---
+## Date, Time & Number Formats
+Never hardcode locale-specific formats. Use the browser's `Intl` API.
+### Date Formats by Region
+| Region | Format | Example |
+|---|---|---|
+| US | MM/DD/YYYY | 01/15/2025 |
+| UK / Australia | DD/MM/YYYY | 15/01/2025 |
+| ISO / Technical | YYYY-MM-DD | 2025-01-15 |
+| Germany | DD.MM.YYYY | 15.01.2025 |
+| Japan | YYYY年MM月DD日 | 2025年01月15日 |
+| Arabic | Right-to-left, varies | Locale-dependent |
+**Always use `Intl.DateTimeFormat`:**
+```javascript
+new Intl.DateTimeFormat('de-DE').format(new Date()) // 15.1.2025
+new Intl.DateTimeFormat('en-US').format(new Date()) // 1/15/2025
+new Intl.DateTimeFormat('ar-SA').format(new Date()) // Arabic numeral date
+```
+### Number Formats
+| Locale | Thousands separator | Decimal separator | Example |
+|---|---|---|---|
+| en-US | , | . | 1,234,567.89 |
+| de-DE | . | , | 1.234.567,89 |
+| fr-FR | (thin space) | , | 1 234 567,89 |
+| ar | (varies) | (varies) | Use Intl API |
+**Always use `Intl.NumberFormat`:**
+```javascript
+new Intl.NumberFormat('de-DE').format(1234567.89) // 1.234.567,89
+```
+### Currency
+- Symbol position varies: `$100` (US) vs `100 €` (Europe) vs `¥100` (Japan)
+- Always use `Intl.NumberFormat` with `style: 'currency'`
+- Never hardcode `$` prefix
+```javascript
+new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(1234)
+// → 1.234,00 €
+```
+---
+## Font Support for Non-Latin Scripts
+Most web fonts only support Latin characters. If you use a custom font and the user's OS language is Arabic, Chinese, Korean, etc., the browser will fall back to a system font — creating a jarring inconsistency.
+### Check Font Coverage
+| Script | Common Web Font Support |
+|---|---|
+| Latin (English, French, German...) | ✅ Most web fonts |
+| Cyrillic (Russian, Bulgarian...) | ✅ Many Google Fonts |
+| Greek | ✅ Many Google Fonts |
+| Arabic | ❌ Most Latin web fonts — needs dedicated Arabic font |
+| Hebrew | ❌ Most Latin web fonts — needs dedicated Hebrew font |
+| CJK (Chinese, Japanese, Korean) | ❌ Most Latin web fonts — system fonts usually |
+| Devanagari (Hindi) | ❌ Most Latin web fonts — Noto fonts or dedicated |
+### Recommended Universal Font: Noto
+Google's **Noto** font family is designed to support all scripts without "tofu" (□ characters). It's a safe fallback for multilingual products.
+### CSS Font Stack for Multilingual
+```css
+font-family: 'YourFont', 'Noto Sans', system-ui, sans-serif;
+```
+---
+## Text in Images
+**Never embed text inside images** if the product will be translated.
+- Images with text can't be localized without recreating the image
+- Screen readers can't read text in images
+- Text in images doesn't scale with browser font settings
+**Solution:** Use CSS text overlays on top of images. Keep the image as a background, text as a separate HTML element.
+---
+## Pluralization
+Languages handle plurals very differently. English has 2 forms (1 item, 2 items). Arabic has 6 plural forms. Russian has 3.
+**Never do this in code:**
+```javascript
+`${count} item${count === 1 ? '' : 's'}` // Only works for English
+```
+**Do this instead:**
+Use an i18n library that handles plural rules (i18next, react-intl, FormatJS):
+```javascript
+t('items', { count }) // Library handles the plural form per locale
+```
+### Design implication: Leave room for plural variations
+In designs, don't assume a short string stays short in all plural forms. "1 item" vs "1,234 items" is one thing — but in some languages, the word itself changes length significantly across plural forms.
+---
+## i18n Design Audit Checklist
+- [ ] No hardcoded strings visible in the UI (all from translation files)
+- [ ] Buttons use `min-width` not fixed width
+- [ ] Fixed-height containers use `min-height` to accommodate expansion
+- [ ] RTL layout tested with `dir="rtl"` (if targeting RTL languages)
+- [ ] Directional icons flip in RTL
+- [ ] Dates use `Intl.DateTimeFormat`
+- [ ] Numbers use `Intl.NumberFormat`
+- [ ] Currency uses `Intl.NumberFormat` with currency style
+- [ ] No text embedded in images
+- [ ] Pluralization handled by an i18n library, not string concatenation
+- [ ] Font stack includes multilingual fallback (Noto or system-ui)
+- [ ] Navigation tested with 40% longer strings

package/skills/design-auditor/references/iconography.md ADDED Viewed

@@ -0,0 +1,201 @@
+# Iconography Rules Reference
+Icons are a universal UI language — but only when used consistently and correctly. Inconsistent iconography is one of the most noticeable signs of an unpolished UI.
+---
+## Choosing an Icon Library
+### The One Library Rule
+Use exactly **one icon library** throughout the product. Mixing libraries creates visual inconsistency because each library has its own optical proportions, stroke weights, and corner rounding.
+### Popular Libraries & Their Character
+| Library | Style | Best For |
+|---|---|---|
+| **Lucide** | Clean outline, 2px stroke | Modern SaaS, developer tools |
+| **Phosphor** | Multi-weight, very versatile | Any product, highly flexible |
+| **Heroicons** | Outline + solid variants | Tailwind-based projects |
+| **Material Symbols** | Google's system | Android-adjacent, data-heavy UIs |
+| **Feather** | Minimal outline | Clean, minimal interfaces |
+| **Tabler Icons** | Outline, very complete | Enterprise tools |
+| **Radix Icons** | Compact, precise | UI components, design systems |
+### Picking a Style
+Each library usually offers multiple styles. Pick **one** and don't mix:
+- **Outline** — light, airy, modern
+- **Filled / Solid** — heavier, more assertive, better at small sizes
+- **Duotone** — two-tone, decorative, good for empty states and illustrations
+- **Bold / Thick** — accessible, high-contrast, punchy
+---
+## Icon Sizing
+### The Optical Grid
+Icons look best at sizes that align to the 4-point grid AND are optical grid-friendly:
+| Size | Use Case |
+|---|---|
+| 12px | Tiny inline indicators (status dots with label) |
+| 16px | Dense UI, inline with small text (12–13px) |
+| 20px | Default inline with body text (14–16px) |
+| 24px | Standard icon button, nav item, list row |
+| 32px | Feature icons, section headings |
+| 40px | Empty state icons, card decorations |
+| 48px | Large empty states, onboarding |
+| 64–96px | Hero illustrations (use SVG illustrations, not icons) |
+**Avoid:** 18px, 22px, 26px, 28px, 36px — these fall between optical grid lines and look slightly off.
+### Matching Icon Size to Text Size
+| Text Size | Paired Icon Size |
+|---|---|
+| 12px | 12–14px |
+| 14px | 16px |
+| 16px | 20px |
+| 18–20px | 24px |
+| 24px+ | 28–32px |
+---
+## Stroke Weight Consistency
+Outline icons have a stroke weight. Mixing stroke weights in the same UI feels inconsistent.
+| Context | Stroke Weight |
+|---|---|
+| Dense UI, small icons (16px) | 1.5px |
+| Standard UI (20–24px) | 2px |
+| Bold/accessible UI | 2.5px |
+| Large decorative icons (32px+) | 1.5–2px (lighter at large sizes) |
+**Rule:** If your icon library uses 2px strokes and you manually scale an icon up, the stroke doesn't scale — it stays 2px. At 48px, a 2px stroke looks too thin. Either use a bolder variant or adjust stroke weight.
+---
+## Optical Alignment
+Icons are not the same as text — they don't sit on the baseline. Aligning them to text requires care.
+### The Bounding Box Problem
+Most icons have invisible padding baked into their bounding box. The actual visual weight sits in the center, but the bounding box is square (24×24px). This means:
+```
+❌ Bad: align icon bounding box to text baseline → icon looks high
+✅ Good: align icon to optical center of adjacent text
+```
+In CSS, use `vertical-align: middle` or flexbox with `align-items: center`:
+```css
+.icon-with-label {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+```
+For inline icons inside text, `vertical-align: -0.125em` (shifting slightly below baseline) often gives the best optical result.
+### Optical Centering in Buttons
+When an icon is inside a button with a label, the icon + label combination should feel optically centered — not mathematically centered. Sometimes this means adding 1–2px more padding on one side.
+---
+## Touch Target Padding
+A 24px icon used as an interactive button is too small to tap comfortably. You need padding.
+```
+Icon size + padding = touch target
+24px icon + 10px padding each side = 44px touch target ✅
+16px icon + 14px padding each side = 44px touch target ✅
+```
+In CSS:
+```css
+.icon-button {
+  width: 44px;
+  height: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* The icon inside is 20–24px; padding provides the rest */
+}
+```
+---
+## Icon Meaning & Consistency
+### Universal Icons (No label needed)
+These are understood cross-culturally and don't need a visible label (but a tooltip is still good practice):
+- ✕ or × — Close
+- ☰ — Menu / hamburger
+- ⌕ / 🔍 — Search
+- ⬆ ⬇ ← → — Directional arrows
+- + — Add
+- ✓ — Confirm / checked
+### Ambiguous Icons (Always need a label)
+These mean different things in different contexts and should always have a visible label:
+- ★ — Could mean favourite, rating, or featured
+- 🔔 — Could mean notifications, alerts, or reminders
+- ⚙ — Could mean settings, configuration, or preferences
+- 📁 — Could mean files, projects, or categories
+- 🏠 — Could mean home page, dashboard, or main menu
+### The Meaning Consistency Rule
+Once an icon has a meaning in your product, that meaning must be consistent everywhere.
+❌ Bad: Using ★ for "favourite" on the home page and ★ for "rating" in the review section
+✅ Good: Using ★ for "favourite" everywhere, and a separate ⭐ filled style for ratings
+---
+## Icon + Label Patterns
+### When to Show Labels
+| Context | Label Required? |
+|---|---|
+| Primary navigation (desktop) | Recommended |
+| Primary navigation (mobile bottom bar) | Required |
+| Toolbar / action bar | Tooltip minimum, label preferred |
+| Inline with text | No (context is enough) |
+| Icon-only button | Tooltip required (`aria-label` always required) |
+| Empty state illustrations | Yes — with heading + body text |
+### Accessibility: aria-label
+Every icon used as a button or interactive element MUST have an `aria-label` even if it has a visual label:
+```html
+<!-- Icon-only button -->
+<button aria-label="Close dialog">
+  <XIcon size={20} />
+</button>
+<!-- Icon + visible label (aria-label still recommended) -->
+<button aria-label="Add new task">
+  <PlusIcon size={16} />
+  Add task
+</button>
+```
+---
+## Common Iconography Mistakes
+| Mistake | Fix |
+|---|---|
+| Mixing outline and filled icons in same UI | Pick one style and stick to it |
+| Using icons from 2+ different libraries | Pick one library |
+| Scaling icons to non-grid sizes (18px, 22px) | Use 16, 20, 24, 32px |
+| Using icon bounding box for alignment | Use optical/flex center alignment |
+| No label on ambiguous icons | Add visible label or tooltip |
+| No `aria-label` on icon buttons | Always add `aria-label` |
+| Icon touch target too small (under 44px) | Add padding to reach 44×44px |
+| Same icon, different meanings in same product | Pick one meaning per icon, use different icons for different meanings |
+| Decreasing icon size on mobile | Icons need to be the same or larger on mobile for touch |

package/skills/design-auditor/references/microcopy.md ADDED Viewed

@@ -0,0 +1,227 @@
+# Microcopy Reference
+Microcopy is the small functional text throughout a UI — button labels, error messages, tooltips, placeholders, confirmations, and empty states. It's often written by developers as an afterthought, but it has an outsized impact on usability and user trust.
+---
+## Button Labels
+### The Verb Rule
+Buttons should always be a **verb** (or verb phrase) that describes the action:
+| ❌ Vague | ✅ Specific |
+|---|---|
+| OK | Got it / Save / Confirm |
+| Submit | Send Message / Create Account / Place Order |
+| Yes | Delete / Remove / Yes, cancel my plan |
+| Cancel | Keep editing / Go back |
+| Upload | Upload photo / Add file |
+| Continue | Next: Shipping / Continue to payment |
+### Rules
+- **Be specific about what happens.** "Save Changes" is better than "Save" when the user might not know what they're saving.
+- **Match the button to the outcome.** If clicking a button sends an email, say "Send Email" — not "Confirm."
+- **Destructive buttons should name the thing being destroyed.** "Delete Project" not just "Delete." "Cancel Subscription" not just "Cancel."
+- **Primary CTA should be 2–4 words max.** Longer labels don't scan well in buttons.
+- **Sentence case, not Title Case.** "Create account" not "Create Account" (unless your brand style is Title Case throughout).
+### Confirmation Dialogs
+A good destructive confirmation dialog has:
+```
+Title:   Delete "Project Alpha"?
+Body:    This will permanently delete the project and all its tasks.
+         This action cannot be undone.
+Buttons: [Cancel]  [Delete project]  ← specific, not just "Delete"
+```
+Never:
+```
+Title:   Are you sure?
+Body:    This action cannot be undone.
+Buttons: [No]  [Yes]
+```
+---
+## Error Messages
+### The Formula
+A good error message answers three questions:
+1. **What went wrong?**
+2. **Why did it go wrong?** (if not obvious)
+3. **How do I fix it?**
+| ❌ Bad | ✅ Good |
+|---|---|
+| Invalid input | Please enter a valid email address |
+| Error | We couldn't save your changes — check your connection and try again |
+| Password incorrect | That password doesn't match — try again or reset your password |
+| Required field | Please add a project name to continue |
+| 500 Internal Server Error | Something went wrong on our end. We're looking into it — try again in a moment |
+| File too large | This file is too large. Maximum size is 10MB |
+### Rules
+- **Don't blame the user.** Passive voice helps: "That email wasn't recognized" vs "You entered an invalid email."
+- **Be specific.** "Something went wrong" is a last resort, not a default.
+- **Tell them what to do next.** End with an action: "try again", "reset your password", "check your connection."
+- **Match your brand's tone.** A playful app can say "Oops! That didn't work." An enterprise tool should stay neutral and professional.
+- **Never expose technical details** to end users. No stack traces, no HTTP status codes, no "null pointer exception."
+- **Keep error messages short.** 1–2 sentences max. If it needs more explanation, link to a help article.
+### Validation Timing
+- **Validate on blur** (when leaving a field) for format errors (email, URL, phone).
+- **Validate on change** for things like password strength (give live feedback).
+- **Validate on submit** for required field checks — don't interrupt typing.
+- **Never validate on every keystroke** for format errors — showing "Invalid email" while the user is still typing is annoying.
+---
+## Placeholder Text
+Placeholders appear inside empty inputs and disappear when the user starts typing. They are **not labels**.
+### What Placeholders Are Good For
+- Showing the expected format: `name@example.com`, `(555) 000-0000`, `YYYY-MM-DD`
+- Giving a short hint: `Search by name or email`
+- Example values: `e.g. Project Alpha`, `e.g. San Francisco`
+### What Placeholders Are NOT Good For
+- Replacing labels (they disappear, users forget what goes there)
+- Long instructions (they get cut off)
+- Required information (users skip it)
+### Rules
+- **Always have a visible label** in addition to placeholder text.
+- **Keep placeholders short** — one phrase, max.
+- **Prefix style** — When showing an example value, write it as `e.g. Project Alpha` (with a space after the period). Avoid `eg:`, `eg.`, or `E.g:` — these are informal and inconsistent. Flag as 🟡 Warning.
+- **Don't duplicate the label** — A placeholder that says exactly the same thing as its label adds no value. Use the placeholder for format hints or examples only.
+- **Placeholder contrast** should be noticeably lighter than real input text — but still meet 3:1 contrast for readability.
+### Citing Placeholder Issues in Audit Reports
+When flagging a placeholder issue, always cite:
+- The exact placeholder text (quoted)
+- The node ID if available from `get_design_context`
+- The specific rule it violates
+Example: 🟡 Placeholder `"eg: 5"` (node 68:27994) — uses informal `eg:` prefix. Use `e.g. 5` or just the unit hint.
+---
+## Tooltips & Helper Text
+### When to Use Tooltips
+- To explain an icon button with no label
+- To clarify a non-obvious field ("API keys are case-sensitive")
+- To explain why something is disabled ("You need admin access")
+### When NOT to Use Tooltips
+- For essential information — if it's critical, put it on the screen, not hidden in a hover
+- For mobile (tooltips don't work on touch — use inline helper text or a modal instead)
+- For long explanations — tooltips should be 1–2 sentences max
+### Helper Text (Below Input)
+Use static helper text below inputs for:
+- Format hints: "Use 8+ characters with at least one number"
+- Consequences: "This will be visible to everyone on your team"
+- Counts: "0/280 characters"
+Position: directly below the input, above where the error message will appear.
+---
+## Tone Guidelines
+### Pick One Tone and Stick to It
+| Tone | Best For | Example |
+|---|---|---|
+| **Friendly & casual** | Consumer apps, social, creative tools | "Looks great! Your changes are saved ✓" |
+| **Warm & professional** | SaaS, productivity, HR tools | "Your changes have been saved." |
+| **Neutral & clinical** | Finance, legal, healthcare, enterprise | "Transaction completed successfully." |
+| **Playful** | Games, kids apps, lifestyle | "Woohoo! You crushed it 🎉" |
+### Consistency Rules
+- If you use contractions ("you're", "we'll") in one place, use them everywhere.
+- If you use first person ("Your account") vs second person ("My account") — pick one.
+- If you address users casually in empty states, don't suddenly switch to formal language in error messages.
+- If your brand is friendly, never let technical/legal copy sneak in with a completely different voice.
+---
+## Terminology Consistency
+One of the most common microcopy mistakes is calling the same concept different things in different parts of the app.
+### How to Audit Terminology
+Search for synonyms being used for the same thing. Common traps:
+| Concept | Don't Mix These |
+|---|---|
+| The user's workspace | "workspace" / "project" / "team" / "organization" |
+| Content items | "task" / "item" / "card" / "ticket" / "to-do" |
+| Saving | "save" / "update" / "apply" / "confirm" |
+| Removing | "delete" / "remove" / "archive" / "clear" |
+| Members | "members" / "users" / "collaborators" / "teammates" |
+### Rule: Pick One Word Per Concept
+Create a short glossary and stick to it. Every button, label, confirmation, and error message should use the same word for the same thing.
+---
+## Numbers, Dates & Formatting
+- **Dates**: Use unambiguous formats. "Jan 15, 2025" or "15 January 2025" beats "01/15/25" (is that Jan 15 or the 1st of the 15th month?).
+- **Relative time**: "2 hours ago" is friendlier than a timestamp for recent events. But always show the full date on hover/focus.
+- **Large numbers**: Use commas: 1,000,000 not 1000000. Or abbreviate for dashboards: 1.2M, 45K.
+- **Percentages**: "You're 75% done" not "75% complete" — the possessive makes it feel personal.
+- **File sizes**: Show in the most readable unit. 1.4 MB not 1,400,000 bytes.
+---
+## Confirmation & Success Messages
+| Action | ✅ Good Confirmation |
+|---|---|
+| Saved | "Changes saved" or "Project saved" |
+| Sent | "Message sent to Jamie" |
+| Deleted | "Task deleted" + Undo option |
+| Copied | "Link copied to clipboard" |
+| Uploaded | "Photo uploaded successfully" |
+| Invited | "Invitation sent to alex@example.com" |
+### Rules
+- **Be specific** — name the thing that was acted on when possible.
+- **Offer undo** for destructive or hard-to-reverse actions.
+- **Don't celebrate too hard** — "🎉 Amazing! You saved a file!" is patronizing. Save enthusiasm for genuinely exciting moments (first project created, subscription upgraded).
+---
+## Required Field Legend
+If asterisks (*) are used to mark required fields, a visible legend must appear in the form — typically at the top or bottom:
+| ✅ Good | ❌ Bad |
+|---|---|
+| "* Required fields" near the form title | Asterisks with no explanation |
+| "Fields marked * are required" | Assuming all users know the convention |
+**Rule:** The `*` convention is widely understood but not universal. A legend is always required for accessibility. Absence of a legend is a 🟢 Tip — not critical, but worth flagging at handoff.
+---
+## Per-Role Text Audit Guide
+When auditing text content in a Figma frame or codebase, classify each text node by role before checking it:
+| Role | How to Identify | Key Rule |
+|---|---|---|
+| **CTA button** | Text inside button/interactive component | Must be a verb. "Save", "Submit", "Send Message" |
+| **Label** | Text above or beside an input field | Must be visible, not placeholder. Required = * with legend |
+| **Placeholder** | Greyed text inside empty input | Format hint only. Never a label replacement |
+| **Error message** | Red/warning text near field or at form top | Answers what/why/how. No blame, no tech jargon |
+| **Empty state** | Text shown when list/content area is empty | Explains the state + gives a next action |
+| **Section header** | Largest text in a content block | Should describe the content, not be decorative |
+| **Confirmation/toast** | Success/feedback text after an action | Names the thing acted on. Offers undo if destructive |
+**Audit citation format:** Always quote the exact text and include the node ID when available.
+`🟡 Button label "Submit" (node 68:27811) — vague verb. Use "Save Changes" or "Send Report" instead.`