design-led-development

Name: design-led-development
Author: jakenuts

github.com/jakenuts设计与 UI2145 次安装16 周前更新

代码仓库

关于 design-led-development

面向产品与工程团队的设计驱动开发技能，帮助在实现功能前审视用户成果、可用性、风险与可衡量性，并以此指导代码和界面决策。

主要功能

01功能开发前的决策框架
02代码清晰与错误处理原则
03性能预算与界面状态要求
04无障碍与隐私检查清单
05表单反馈与质量发布门槛

适用场景

01评估功能是否解决明确的用户需求
02规划交互组件的加载与错误状态
03在发布前检查安全、性能和无障碍

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jakenuts/agent-skills --skill design-led-development

安装后在 Claude Code 中输入/design-led-development确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

COLOR_TOKENS.md

COMPONENT_PATTERNS.md

DOCUMENTATION.md

TESTING.md

详细介绍

设计驱动开发

构建让人觉得理所当然、值得信赖且令人愉悦的系统。每一行代码都服务于人的需求。

核心决策框架

编写任何功能之前，请依次回答以下问题：

用户成果：“这能通过[机制]帮助[用户]实现[成果]”
焦虑/控制感：这会减轻用户的焦虑，还是增强用户的控制感？
简单性：这是最简单的解决方案吗？
可衡量性：我们能衡量成功与否吗？
失败模式：失败模式是什么？如果后果灾难性，请添加防护措施
恢复：用户能从错误中恢复吗？

如果你无法用一句话阐明用户成果，就先不要编写代码。

代码原则

清晰胜于巧妙

// ✅ 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);

注释解释为什么，而非是什么。需要警惕的措辞：“只需”“简单地”“显然”。

明确处理错误

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

async function fetchUser(id: string): Promise<Result<User>> {
  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");

网络韧性

// ✅ DO: Exponential backoff with jitter
const retryWithBackoff = async <T>(
  fn: () => Promise<T>, 
  maxRetries = 3
): Promise<T> => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const delay = Math.min(1000 * 2 ** i + Math.random() * 1000, 10000);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw new Error('Max retries exceeded');
};

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

性能预算

在编写代码前设定以下指标：

指标	预算
冷启动	中端设备上 < 2s
交互响应	感知延迟 < 100ms
动画	每帧 < 16ms（60fps）
API 调用（p95）	< 500ms

将性能回退视为 P0 级 Bug。在低端设备上进行性能分析。

UI 组件状态

每个交互式组件都必须处理所有状态：

✅ Default (idle)
✅ Hover (pointer devices)
✅ Active/pressed
✅ Focus (keyboard navigation)
✅ Disabled (with explanation why)
✅ Loading (with progress indication)
✅ Error (with recovery action)
✅ Success (with next step)
✅ Empty (with helpful onboarding)

视觉系统

间距（8pt 网格）

4px:  Tight grouping (icon + label)
8px:  Related items (form fields in group)
16px: Section separation
24px: Component boundaries
32px: Major sections
48px: Screen-level padding

字体排版比例

H1: 32-40px, bold, line-height 1.2
H2: 24-28px, semibold, line-height 1.3
H3: 20-24px, semibold, line-height 1.4
Body: 16-18px, regular, line-height 1.5
Caption: 14px, regular, line-height 1.4

RULE: Never below 14px for body text (accessibility)

动效

用途	时长	缓动
微交互	100-200ms	ease-out
屏幕切换	300-400ms	ease-in-out
加载状态	600ms+	linear

规则：

动画用于解释，绝不用于装饰
尊重 prefers-reduced-motion
绝不延迟用户操作

无障碍要求

不可妥协的检查清单：

使用语义化 HTML 和 ARIA 标签
所有交互均支持键盘导航
色彩对比度：最低 4.5:1（正文文本为 7:1）
触控目标：最低 44x44pt
经过屏幕阅读器测试
尊重 prefers-reduced-motion
尊重 prefers-color-scheme

信任架构

每项功能都必须回答：

收集的数据：收集哪些数据？（尽量少收集）
失败模式：可能出现什么问题？（优先设计失败场景）
信任信号：如何证明安全？（让其清晰可见）
可逆性：用户能撤销吗？（提交前先预览）
数据去向：他们的数据会怎样处理？（明确说明，而非藏在服务条款中）

隐私默认值

// ✅ DO: Default private, opt-in sharing
const defaultSettings = {
  shareAnalytics: false,
  publicProfile: false,
  dataRetention: 'minimum'
};

// ✅ DO: Redact PII in logs
logger.info('user_action', {
  action: 'profile_update',
  userId: hashUserId(user.id), // Never raw PII
  duration_ms: 234,
  success: true
});

表单验证

在失焦时验证，不要在每次按键时验证
在字段附近内联显示错误
出错时保留用户输入（绝不清空）
为长表单自动保存草稿
仅在表单无效时禁用提交，并说明原因

反馈循环

每个用户操作都需要得到反馈：

类型	时机	示例
即时	< 100ms	按钮按下时的视觉反馈
进度	操作耗时 > 1s	加载指示器
完成	成功后	显示“已保存”并提示下一步
失败	出错时	说明发生了什么以及如何解决

错误消息绝不责怪用户。

反模式

代码反模式（绝不这样做）

❌ 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 反模式（绝不这样做）

❌ 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

安全检查清单

清理所有用户输入（防止 XSS）
使用参数化查询（防止 SQL 注入）
对所有端点进行速率限制
对会更改状态的操作使用 CSRF 令牌
对静态存储的 PII 进行加密（AES-256）
所有网络流量均使用 TLS 1.3
使用 bcrypt/Argon2 对密码进行哈希处理
Cookie 设置 HttpOnly、Secure、SameSite 属性

质量门槛（发布前）

最终使命

每段代码都应切实改善某个人的生活。

如果无法说明它能为用户带来什么好处，就不要发布
如果无法衡量结果，就添加监测
如果无法维护，就简化
如果它没有让人觉得理所当然，就重新设计

质量不容妥协。速度来自清晰，而非捷径。

支持 Markdown

登录后评论