Skip to content

balsm-health/website / .cursor/skills/impeccable

impeccable

Flagged

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

FileKindSize
SKILL.mdskill md19.0 KB
reference/adapt.mdmarkdown9.9 KB
reference/animate.mdmarkdown10.1 KB
reference/audit.mdmarkdown7.1 KB
reference/bolder.mdmarkdown6.3 KB
reference/brand.mdmarkdown10.2 KB
reference/clarify.mdmarkdown10.4 KB
reference/codex.mdmarkdown6.8 KB
reference/colorize.mdmarkdown13.2 KB
reference/craft.mdmarkdown11.7 KB
reference/critique.mdmarkdown35.3 KB
reference/delight.mdmarkdown9.5 KB
reference/distill.mdmarkdown5.5 KB
reference/document.mdmarkdown27.2 KB
reference/extract.mdmarkdown3.3 KB
reference/harden.mdmarkdown8.4 KB
reference/hooks.mdmarkdown7.4 KB
reference/init.mdmarkdown12.4 KB
reference/interaction-design.mdmarkdown6.4 KB
reference/layout.mdmarkdown8.5 KB
reference/live.mdmarkdown58.3 KB
reference/onboard.mdmarkdown7.6 KB
reference/optimize.mdmarkdown7.4 KB
reference/overdrive.mdmarkdown8.8 KB
reference/polish.mdmarkdown12.7 KB
reference/product.mdmarkdown3.7 KB
reference/quieter.mdmarkdown4.7 KB
reference/shape.mdmarkdown11.1 KB
reference/typeset.mdmarkdown13.9 KB
scripts/command-metadata.jsonconfig7.8 KB
scripts/context-signals.mjsscript7.9 KB
scripts/context.mjsscript10.3 KB
scripts/critique-storage.mjsscript8.8 KB
scripts/detect-csp.mjsscript6.6 KB
scripts/detect.mjsscript620 B
scripts/detector/browser/injected/index.mjsscript75.0 KB
scripts/detector/cli/main.mjsscript10.8 KB
scripts/detector/design-system.mjsscript24.1 KB
scripts/detector/detect-antipatterns-browser.jsscript211.7 KB
scripts/detector/detect-antipatterns.mjsscript1.8 KB
scripts/detector/engines/browser/detect-url.mjsscript9.7 KB
scripts/detector/engines/regex/detect-text.mjsscript23.9 KB
scripts/detector/engines/static-html/css-cascade.mjsscript33.6 KB
scripts/detector/engines/static-html/detect-html.mjsscript9.7 KB
scripts/detector/engines/visual/screenshot-contrast.mjsscript6.4 KB
scripts/detector/findings.mjsscript363 B
scripts/detector/node/file-system.mjsscript6.7 KB
scripts/detector/profile/profiler.mjsscript4.4 KB
scripts/detector/registry/antipatterns.mjsscript18.2 KB
scripts/detector/rules/checks.mjsscript113.1 KB
scripts/detector/shared/color.mjsscript4.4 KB
scripts/detector/shared/constants.mjsscript4.1 KB
scripts/detector/shared/page.mjsscript252 B
scripts/hook-admin.mjsscript22.8 KB
scripts/hook-before-edit.mjsscript16.2 KB
scripts/hook-lib.mjsscript54.7 KB
scripts/hook.mjsscript2.0 KB
scripts/lib/design-parser.mjsscript25.2 KB
scripts/lib/impeccable-config.mjsscript21.0 KB
scripts/lib/impeccable-paths.mjsscript3.8 KB
scripts/lib/is-generated.mjsscript2.2 KB
scripts/live-accept.mjsscript29.6 KB
scripts/live-browser-dom.jsscript4.2 KB
scripts/live-browser-session.jsscript3.2 KB
scripts/live-browser.jsscript423.7 KB
scripts/live-commit-manual-edits.mjsscript41.1 KB
scripts/live-complete.mjsscript2.9 KB
scripts/live-copy-edit-agent.mjsscript28.2 KB
scripts/live-discard-manual-edits.mjsscript1.6 KB
scripts/live-inject.mjsscript22.1 KB
scripts/live-insert.mjsscript8.9 KB
scripts/live-manual-edit-evidence.mjsscript11.4 KB
scripts/live-poll.mjsscript13.2 KB
scripts/live-resume.mjsscript4.4 KB
scripts/live-server.mjsscript41.5 KB
scripts/live-status.mjsscript2.1 KB
scripts/live-wrap.mjsscript35.1 KB
scripts/live.mjsscript8.3 KB
scripts/live/browser-script-parts.mjsscript1.7 KB
scripts/live/completion.mjsscript969 B
scripts/live/event-validation.mjsscript6.2 KB
scripts/live/insert-ui.mjsscript15.3 KB
scripts/live/manual-apply.mjsscript34.1 KB
scripts/live/manual-edit-routes.mjsscript14.6 KB
scripts/live/manual-edits-buffer.mjsscript5.0 KB
scripts/live/session-store.mjsscript10.4 KB
scripts/live/svelte-component.mjsscript27.2 KB
scripts/live/sveltekit-adapter.mjsscript9.1 KB
scripts/live/ui-core.mjsscript5.4 KB
scripts/live/vocabulary.mjsscript3.2 KB
scripts/modern-screenshot.umd.jsscript28.6 KB
scripts/palette.mjsscript56.9 KB
scripts/pin.mjsscript6.0 KB

reference/harden.md

View on GitHub
Designs that only work with perfect data aren't production-ready. Harden the interface against the inputs, errors, languages, and network conditions that real users will throw at it.

## Assess Hardening Needs

Identify weaknesses and edge cases:

1. **Test with extreme inputs**:
   - Very long text (names, descriptions, titles)
   - Very short text (empty, single character)
   - Special characters (emoji, RTL text, accents)
   - Large numbers (millions, billions)
   - Many items (1000+ list items, 50+ options)
   - No data (empty states)

2. **Test error scenarios**:
   - Network failures (offline, slow, timeout)
   - API errors (400, 401, 403, 404, 500)
   - Validation errors
   - Permission errors
   - Rate limiting
   - Concurrent operations

3. **Test internationalization**:
   - Long translations (German is often 30% longer than English)
   - RTL languages (Arabic, Hebrew)
   - Character sets (Chinese, Japanese, Korean, emoji)
   - Date/time formats
   - Number formats (1,000 vs 1.000)
   - Currency symbols

**CRITICAL**: Designs that only work with perfect data aren't production-ready. Harden against reality.

## Hardening Dimensions

Systematically improve resilience:

### Text Overflow & Wrapping

**Long text handling**:
```css
/* Single line with ellipsis */
.truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

/* Multi-line with clamp */
.line-clamp {
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

/* Allow wrapping */
.wrap {
  word-wrap: break-word;
  overflow-wrap: break-word;
  hyphens: auto;
}
```

**Flex/Grid overflow**:
```css
/* Prevent flex items from overflowing */
.flex-item {
  min-width: 0; /* Allow shrinking below content size */
  overflow: hidden;
}

/* Prevent grid items from overflowing */
.grid-item {
  min-width: 0;
  min-height: 0;
}
```

**Responsive text sizing**:
- Use `clamp()` for fluid typography
- Set minimum readable sizes (14px on mobile)
- Test text scaling (zoom to 200%)
- Ensure containers expand with text

### Internationalization (i18n)

**Text expansion**:
- Add 30-40% space budget for translations
- Use flexbox/grid that adapts to content
- Test with longest language (usually German)
- Avoid fixed widths on text containers

```jsx
// ❌ Bad: Assumes short English text
<button className="w-24">Submit</button>

// ✅ Good: Adapts to content
<button className="px-4 py-2">Submit</button>
```

**RTL (Right-to-Left) support**:
```css
/* Use logical properties */
margin-inline-start: 1rem; /* Not margin-left */
padding-inline: 1rem; /* Not padding-left/right */
border-inline-end: 1px solid; /* Not border-right */

/* Or use dir attribute */
[dir="rtl"] .arrow { transform: scaleX(-1); }
```

**Character set support**:
- Use UTF-8 encoding everywhere
- Test with Chinese/Japanese/Korean (CJK) characters
- Test with emoji (they can be 2-4 bytes)
- Handle different scripts (Latin, Cyrillic, Arabic, etc.)

**Date/Time formatting**:
```javascript
// ✅ Use Intl API for proper formatting
new Intl.DateTimeFormat('en-US').format(date); // 1/15/2024
new Intl.DateTimeFormat('de-DE').format(date); // 15.1.2024

new Intl.NumberFormat('en-US', { 
  style: 'currency', 
  currency: 'USD' 
}).format(1234.56); // $1,234.56
```

**Pluralization**:
```javascript
// ❌ Bad: Assumes English pluralization
`${count} item${count !== 1 ? 's' : ''}`

// ✅ Good: Use proper i18n library
t('items', { count }) // Handles complex plural rules
```

### Error Handling

**Network errors**:
- Show clear error messages
- Provide retry button
- Explain what happened
- Offer offline mode (if applicable)
- Handle timeout scenarios

```jsx
// Error states with recovery
{error && (
  <ErrorMessage>
    <p>Failed to load data. {error.message}</p>
    <button onClick={retry}>Try again</button>
  </ErrorMessage>
)}
```

**Form validation errors**:
- Inline errors near fields
- Clear, specific messages
- Suggest corrections
- Don't block submission unnecessarily
- Preserve user input on error

**API errors**:
- Handle each status code appropriately
  - 400: Show validation errors
  - 401: Redirect to login
  - 403: Show permission error
  - 404: Show not found state
  - 429: Show rate limit message
  - 500: Show generic error, offer support

**Graceful degradation**:
- Core functionality works without JavaScript
- Images have alt text
- Progressive enhancement
- Fallbacks for unsupported features

### Edge Cases & Boundary Conditions

**Empty states**:
- No items in list
- No search results
- No notifications
- No data to display
- Provide clear next action

**Loading states**:
- Initial load
- Pagination load
- Refresh
- Show what's loading ("Loading your projects...")
- Time estimates for long operations

**Large datasets**:
- Pagination or virtual scrolling
- Search/filter capabilities
- Performance optimization
- Don't load all 10,000 items at once

**Concurrent operations**:
- Prevent double-submission (disable button while loading)
- Handle race conditions
- Optimistic updates with rollback
- Conflict resolution

**Permission states**:
- No permission to view
- No permission to edit
- Read-only mode
- Clear explanation of why

**Browser compatibility**:
- Polyfills for modern features
- Fallbacks for unsupported CSS
- Feature detection (not browser detection)
- Test in target browsers

### Input Validation & Sanitization

**Client-side validation**:
- Required fields
- Format validation (email, phone, URL)
- Length limits
- Pattern matching
- Custom validation rules

**Server-side validation** (always):
- Never trust client-side only
- Validate and sanitize all inputs
- Protect against injection attacks
- Rate limiting

**Constraint handling**:
```html
<!-- Set clear constraints -->
<input 
  type="text"
  maxlength="100"
  pattern="[A-Za-z0-9]+"
  required
  aria-describedby="username-hint"
/>
<small id="username-hint">
  Letters and numbers only, up to 100 characters
</small>
```

### Accessibility Resilience

**Keyboard navigation**:
- All functionality accessible via keyboard
- Logical tab order
- Focus management in modals
- Skip links for long content

**Screen reader support**:
- Proper ARIA labels
- Announce dynamic changes (live regions)
- Descriptive alt text
- Semantic HTML

**Motion sensitivity**:
```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}
```

**High contrast mode**:
- Test in Windows high contrast mode
- Don't rely only on color
- Provide alternative visual cues

### Performance Resilience

**Slow connections**:
- Progressive image loading
- Skeleton screens
- Optimistic UI updates
- Offline support (service workers)

**Memory leaks**:
- Clean up event listeners
- Cancel subscriptions
- Clear timers/intervals
- Abort pending requests on unmount

**Throttling & Debouncing**:
```javascript
// Debounce search input
const debouncedSearch = debounce(handleSearch, 300);

// Throttle scroll handler
const throttledScroll = throttle(handleScroll, 100);
```

## Testing Strategies

**Manual testing**:
- Test with extreme data (very long, very short, empty)
- Test in different languages
- Test offline
- Test slow connection (throttle to 3G)
- Test with screen reader
- Test keyboard-only navigation
- Test on old browsers

**Automated testing**:
- Unit tests for edge cases
- Integration tests for error scenarios
- E2E tests for critical paths
- Visual regression tests
- Accessibility tests (axe, WAVE)

**IMPORTANT**: Hardening is about expecting the unexpected. Real users will do things you never imagined.

**NEVER**:
- Assume perfect input (validate everything)
- Ignore internationalization (design for global)
- Leave error messages generic ("Error occurred")
- Forget offline scenarios
- Trust client-side validation alone
- Use fixed widths for text
- Assume English-length text
- Block entire interface when one component errors

## Verify Hardening

Test thoroughly with edge cases:

- **Long text**: Try names with 100+ characters
- **Emoji**: Use emoji in all text fields
- **RTL**: Test with Arabic or Hebrew
- **CJK**: Test with Chinese/Japanese/Korean
- **Network issues**: Disable internet, throttle connection
- **Large datasets**: Test with 1000+ items
- **Concurrent actions**: Click submit 10 times rapidly
- **Errors**: Force API errors, test all error states
- **Empty**: Remove all data, test empty states

When edge cases are covered, hand off to `/impeccable polish` for the final pass.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall