design-decisions
强制记录每个重要设计决策背后的推理过程。创建解释为何做出选择、考虑过哪些替代方案以及接受的权衡的决策日志。防止未经证明的"默认"选择。
name: design-decisions description: Forces documentation of the reasoning behind every significant design decision. Creates a decision log that explains WHY choices were made, alternatives considered, and trade-offs accepted. Prevents unjustified "default" choices.
Design Decision Logger Skill
You are operating with design decision logging capabilities. This skill ensures that every significant design choice has documented reasoning — transforming unconscious defaults into conscious decisions.
Core Philosophy
"Great design isn't about creating features; it's about intentionality."
AI design fails not because it picks the "wrong" options, but because it picks options without reasons. A design where every choice has documented justification will always be better than one with "good defaults."
Why Log Decisions?
For the current design:
- Forces examination of unconscious defaults
- Reveals unjustified choices that need reconsideration
- Creates accountability for design quality
For future iteration:
- Explains WHY something is the way it is
- Enables informed changes (not breaking things accidentally)
- Teaches newcomers the design rationale
For collaboration:
- Makes critique more productive ("I understand why, but...")
- Enables delegation without loss of context
- Creates institutional memory
What Counts as a "Significant Decision"?
Log decisions that: - Affect multiple components or screens - Establish a pattern that will be repeated - Required choosing between viable alternatives - Override a common convention or expectation - Will be questioned by someone reviewing the designDon't log:
- Individual pixel values within an established system
- Obvious choices with no real alternatives
- Temporary implementations meant to be revisited
Decision Categories
1. Typography Decisions
**Font Family:** ```xml Geist Sans Our users are developers. Geist is designed specifically for developer tools, embodying "simplicity, minimalism, and speed" which aligns with our principle of "professional precision." Rejected: Overused in our competitive space (Linear, Vercel, Notion all use it). We need differentiation. Rejected: Platform-specific. We need cross-platform consistency. Considered: Good option, but Geist's mono variant is better integrated. Would reconsider if Geist unavailable. - Less personality than a distinctive display font - Requires hosting (not a system font) + Excellent readability at all sizes + Consistent with developer tool expectations Medium — would require full rebrand to change ```Type Scale:
<decision category="typography" element="type-scale">
<choice>1.25 ratio (Major Third): 12, 15, 19, 24, 30, 37</choice>
<reason>
Moderate ratio provides clear hierarchy without dramatic jumps.
Appropriate for information-dense interfaces where many levels
of hierarchy are needed.
</reason>
<alternatives>
<alternative name="1.5 ratio (Perfect Fifth)">
Rejected: Too dramatic for our dense UI. Would require
too much scrolling to accommodate large headings.
</alternative>
<alternative name="1.125 ratio (Major Second)">
Rejected: Too subtle. Hierarchy becomes unclear, especially
when combined with weight variations.
</alternative>
</alternatives>
</decision>
2. Color Decisions
**Primary Color:** ```xml #0066FF (Vibrant blue) Blue conveys trust and professionalism (aligned with "professional precision" principle). This specific shade is: - Distinct from competitor blues (Stripe's is lighter, Linear's is different hue) - Accessible against both white and dark backgrounds - Energetic enough to serve as CTA color Rejected: Too associated with AI/generic SaaS. Would blend in rather than differentiate. Rejected: Green implies success/completion. Wrong semantic for primary actions. - White text on this blue: 4.8:1 (AA pass) - This blue on white: 4.8:1 (AA pass) - Tested with Coblis for color blindness visibility ```Color Palette Philosophy:
<decision category="color" element="palette-philosophy">
<choice>Monochromatic base + single accent</choice>
<reason>
Our UI is information-dense. Multiple colors would create
visual chaos. Single accent creates clear affordances
(blue = interactive). Grayscale hierarchy for content.
</reason>
<principles_served>
- "Professional precision" — not playful multicolor
- "Focus on content" — color doesn't distract
</principles_served>
</decision>
3. Spacing Decisions
**Base Unit:** ```xml 4px base unit 4px allows fine-grained control while maintaining consistency. 8px would be too coarse for our dense UI. Scale: 4, 8, 12, 16, 24, 32, 48, 64. Rejected: Jumps between 8 and 16 too large for subtle adjustments in dense layouts. CSS custom properties: --space-1 through --space-8 Tailwind: Extended spacing scale ```Component Density:
<decision category="spacing" element="density">
<choice>Compact density (less padding than typical)</choice>
<reason>
Power users (our target) prefer information density. They're
scanning, not reading. Reference: Linear, GitHub, VS Code
all use compact density for professional tools.
</reason>
<trade_offs>
- Harder for beginners
- Requires careful touch target sizing
+ More visible at once
+ Feels professional/powerful
</trade_offs>
</decision>
4. Layout Decisions
**Page Structure:** ```xml Fixed sidebar + fluid content area Sidebar provides consistent navigation anchor. Fluid content allows adaptation to data needs. Reference: Linear, Notion, VS Code all use this pattern for tool-based products. Rejected: Loses vertical space. Our users have wide screens; horizontal space is abundant. Accepted as option: Sidebar can collapse for full-focus mode. ```Grid System:
<decision category="layout" element="grid">
<choice>12-column grid with 24px gutters</choice>
<reason>
12 divides evenly by 2, 3, 4, 6 — maximum flexibility.
24px gutters balance density with breathing room.
</reason>
<responsive_behavior>
- Desktop: 12 columns
- Tablet: 8 columns
- Mobile: 4 columns
</responsive_behavior>
</decision>
5. Component Decisions
**Button Styles:** ```xml Primary: Filled blue, white text Secondary: Outlined, blue border, blue text Tertiary: Text only, blue text Destructive: Filled red for dangerous actions Visual hierarchy matches importance hierarchy. Fill = most important, outline = alternative option, text = least prominent. Color coding (blue vs red) adds semantic meaning. Default: 36px height (comfortable click target) Small: 28px (for dense contexts) Large: 44px (for primary page actions) ```Form Inputs:
<decision category="components" element="inputs">
<choice>Bottom border only (not full border)</choice>
<reason>
Reduces visual noise in forms with many fields. Lighter
appearance aligns with "professional precision" — not
chunky or heavy.
</reason>
<alternatives>
<alternative name="Full border">
Available as variant: For isolated inputs or emphasis.
</alternative>
</alternatives>
<accessibility>
Border color meets 3:1 contrast for UI components.
Focus state adds left border + background shift.
</accessibility>
</decision>
6. Motion Decisions
**Animation Philosophy:** ```xml Functional motion only — no decorative animation Our users are power users doing focused work. Animation should communicate state changes, not entertain. Every animation must answer: "What information does this convey?" - Page transitions (context: what changed) - Loading states (progress: something is happening) - Feedback (confirmation: action succeeded/failed) - Reveals (hierarchy: new content appearing) - Hover effects (too noisy at high interaction rates) - Idle states (distracting) - "Personality" animations (off-brand) ```Timing:
<decision category="motion" element="timing">
<choice>
Micro-interactions: 150ms
Component transitions: 200ms
Page transitions: 300ms
Easing: cubic-bezier(0.4, 0, 0.2, 1) (Material "standard")
</choice>
<reason>
Fast enough to feel instant, slow enough to be perceived.
Consistent easing creates unified feel. Material easing
is well-tested and feels natural.
</reason>
</decision>
Decision Log Template
```xml Project name Date Date Who made/documented these decisions Principle name Principle name What was decided The decision made Why this choice serves our users/principles What we gave up What we gained 1, 2 easy/medium/hard DES-000 (if dependent on another decision)<!-- More decisions... -->
What needs to be decided
Possible choices
What this blocks
```
Validation Questions
For each logged decision, verify:
1. **"Why this?"** — Can you explain the choice without saying "it looks good"? 2. **"Why not that?"** — Can you explain why alternatives were rejected? 3. **"For whom?"** — Does this serve the specific users defined in the brief? 4. **"According to what?"** — Which design principle does this support? 5. **"What if wrong?"** — How hard is this to change later?Red Flags
Decisions that need reconsideration:
- **"It's the default"** — Not a reason. Why is the default right for us? - **"Everyone does it"** — Not a reason. Why is convention right here? - **"It looks good"** — Not a reason. Good for whom? In what context? - **"I like it"** — Not a reason. User preference trumps designer preference. - **No alternatives listed** — Did you actually consider options? - **Principle not referenced** — How does this serve the design goals?Output Summary
```xml N N with complete reasoning N missing justification N N N N N N N What's problematic How to fix Score 1-10 with explanation of how well decisions are justified ```Key Principle
"It feels like a person looked at it and said, 'This is it.'" — On Linear's design
Every decision in a great design system should feel like someone cared about it specifically. The decision log is proof of that care.