Design Led Development

Design-Led Development

Build systems that feel inevitable, trustworthy, and delightful. Every line of code serves a human outcome.

Core Decision Framework

Before writing any feature, answer these questions in order:

1. User outcome: "This helps [user] achieve [outcome] by [mechanism]"
2. Anxiety/control: Does this reduce user anxiety or increase user control?
3. Simplicity: Is this the simplest solution?
4. Measurability: Can we measure success?
5. Failure mode: What's the failure mode? If catastrophic, add safeguards
6. Recovery: Can users recover from errors?

If you cannot articulate the user outcome in one sentence, do not code it yet.

Code Principles

Clarity Over Cleverness

// ✅ DO: Name for humans reading at 2am
const userAuthenticationStatus = checkAuth(userId);
const formattedOrderDate = formatDate(order.createdAt);

// ❌ DON'T: Clever but obscure
const x = chk(u);
const d = fmt(o.c);

Comments explain why, not what. Red flag phrases: "just", "simply", "obviously".

Explicit Error Handling

// ✅ DO: Error states as return types
type Result = 
  | { success: true; data: T } 
  | { success: false; error: UserFacingError };

async function fetchUser(id: string): Promise> {
  try {
    const user = await api.getUser(id);
    return { success: true, data: user };
  } catch (error) {
    return { 
      success: false, 
      error: { 
        message: "Unable to load user profile",
        action: "Please try again or contact support"
      }
    };
  }
}

// ❌ NEVER: Generic errors or silent failures
throw new Error("Something went wrong");

Network Resilience

// ✅ DO: Exponential backoff with jitter
const retryWithBackoff = async (
  fn: () => Promise, 
  maxRetries = 3
): Promise => {
  for (let i = 0; i  setTimeout(resolve, delay));
    }
  }
  throw new Error('Max retries exceeded');
};

// ✅ DO: Timeout promises
const withTimeout = (promise: Promise, ms: number): Promise =>
  Promise.race([
    promise,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('Request timeout')), ms)
    )
  ]);

Performance Budgets

Set these before coding:

| Metric | Budget | |--------|--------| | Cold start | 1s operations | Loading indicator | | Completion | After success | "Saved" with next step | | Failure | On error | What happened + how to fix |

Never blame the user in error messages.

Anti-Patterns

Code Anti-Patterns (Never Do)

❌ Magic numbers without constants
❌ Functions over 50 lines
❌ God objects over 300 lines
❌ Mutable global state
❌ Side effects not in function name
❌ Catching errors without handling
❌ Copy-pasted code

UX Anti-Patterns (Never Do)

❌ Forced account creation before value
❌ Dark patterns (hidden costs, trick questions)
❌ Generic error messages ("Error 500")
❌ Modal dialogs for everything
❌ Destroying data without confirmation
❌ Disabling paste in password fields
❌ Auto-playing video/audio
❌ Infinite scroll without pagination option

Security Checklist

• [ ] Sanitize all user input (XSS prevention)
• [ ] Parameterized queries (SQL injection prevention)
• [ ] Rate limit all endpoints
• [ ] CSRF tokens for state-changing operations
• [ ] Encrypt PII at rest (AES-256)
• [ ] TLS 1.3 for all network traffic
• [ ] Hash passwords with bcrypt/Argon2
• [ ] HttpOnly, Secure, SameSite cookies

Quality Gates (Before Ship)

• [ ] Lighthouse score > 90
• [ ] Zero critical/high security vulnerabilities
• [ ] Core flows work offline or degrade gracefully
• [ ] Keyboard navigation works
• [ ] Screen reader tested (VoiceOver + NVDA)
• [ ] Error states tested
• [ ] Load tested at 2x expected peak
• [ ] Mobile tested on real devices
• [ ] Privacy review completed
• [ ] Rollback procedure documented

Final Mandate

Every piece of code should make someone's life measurably better.

• If you cannot explain the user benefit, do not ship it
• If you cannot measure the outcome, instrument it
• If you cannot maintain it, simplify it
• If it does not feel inevitable, redesign it

Quality is not negotiable. Speed is achieved through clarity, not shortcuts.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jakenuts
• Source: jakenuts/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.