wordle/.claude/skills/wds-7-design-system/steps-c/step-03-calculate-similarity.md

---

name: 'step-03-calculate-similarity' description: 'Interpret comparison data, calculate weighted similarity score, and classify similarity level'

File References

nextStepFile: './step-04-identify-opportunities.md'

Step 3: Calculate Similarity

STEP GOAL:

Interpret the comparison data, apply weighted scoring to calculate an overall similarity percentage, classify the similarity level, and generate an initial recommendation.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Similarity Levels

Level 1: Identical (95-100%)

Characteristics:

• All visual attributes match
• Same functional purpose
• Same behavioral patterns
• Only content differs (labels, text)

Interpretation: This is the same component

Recommendation: Reuse existing component reference

---

Level 2: Very High Similarity (80-94%)

Characteristics:

• Visual attributes mostly match
• Same core function
• Minor behavioral differences
• Same usage context

Interpretation: This is likely the same component with minor variations

Recommendation: Consider adding variant to existing component

---

Level 3: High Similarity (65-79%)

Characteristics:

• Visual attributes similar
• Related functional purpose
• Some behavioral differences
• Similar usage context

Interpretation: Could be same component or new variant

Recommendation: Designer decision needed - variant or new?

---

Level 4: Medium Similarity (45-64%)

Characteristics:

• Some visual overlap
• Different functional purpose
• Different behaviors
• Different usage context

Interpretation: Related but distinct components

Recommendation: Likely new component, but designer should confirm

---

Level 5: Low Similarity (20-44%)

Characteristics:

• Minimal visual overlap
• Different function
• Different behaviors
• Different context

Interpretation: Different components that happen to share a type

Recommendation: Create new component

---

Level 6: No Similarity (<20%)

Characteristics:

• No meaningful overlap
• Completely different purpose
• Unrelated patterns

Interpretation: Unrelated components

Recommendation: Definitely create new component

---

Calculation Logic

Calculate overall similarity:

1. Weight each dimension:

   • Visual: 30%
   • Functional: 30%
   • Behavioral: 25%
   • Contextual: 15%

2. Convert dimension scores to numeric:

   • High = 1.0
   • Medium = 0.6
   • Low = 0.2

3. Calculate weighted average:

   • Overall = (Visual × 0.3) + (Functional × 0.3) + (Behavioral × 0.25) + (Contextual × 0.15)

4. Convert to percentage:

   • Similarity % = Overall × 100

Example:

Dimension Scores:
- Visual: High (1.0)
- Functional: Medium (0.6)
- Behavioral: Medium (0.6)
- Contextual: Medium (0.6)

Calculation:
(1.0 × 0.3) + (0.6 × 0.3) + (0.6 × 0.25) + (0.6 × 0.15)
= 0.3 + 0.18 + 0.15 + 0.09
= 0.72

Similarity: 72% (High Similarity - Level 3)

---

Step 1: Calculate Score

Apply calculation logic to comparison data

``` 📊 Similarity Calculation Visual: High (1.0) × 30% = 0.30 Functional: Medium (0.6) × 30% = 0.18 Behavioral: Medium (0.6) × 25% = 0.15 Contextual: Medium (0.6) × 15% = 0.09 Overall Similarity: 72% Level: High Similarity (Level 3) ```

---

Step 2: Classify Similarity

Map percentage to similarity level

``` **Similarity Level: High (72%)** This component is similar to Button [btn-001] but has some differences. Could be: - A variant of the existing button - A new related button component Designer decision needed. ```

---

Step 3: Generate Recommendation

Based on similarity level, generate recommendation with reasoning

For Level 1-2 (Identical/Very High):

✅ Recommendation: Reuse existing component

Reasoning:

- Components are nearly identical
- Only content/labels differ
- Same visual and behavioral patterns
- Maintaining consistency is straightforward

For Level 3 (High):

🤔 Recommendation: Designer decision needed

This could go either way:

- Similar enough to be a variant
- Different enough to be separate

I'll present the trade-offs so you can decide.

For Level 4-5 (Medium/Low):

🆕 Recommendation: Create new component

Reasoning:

- Significant functional differences
- Different usage contexts
- Trying to merge would create complexity
- Better to keep separate

For Level 6 (No similarity):

✅ Recommendation: Definitely create new component

Reasoning:

- Components are fundamentally different
- No meaningful overlap
- No benefit to linking them

---

Step 4: Identify Key Decision Factors

Highlight the most important differences that affect the decision

Example:

🔑 Key Decision Factors:

1. **Icon presence** - Current has icon, existing doesn't
   Impact: Visual consistency, component complexity

2. **Loading state** - Current has loading, existing doesn't
   Impact: Behavioral complexity, reusability

3. **Navigation vs Submission** - Different purposes
   Impact: Semantic meaning, developer understanding

These differences will affect your decision.

---

Step 5: Pass to Next Step

Pass classification and recommendation to opportunity identification:

• Similarity level
• Recommendation
• Key decision factors

Next: step-04-identify-opportunities.md

---

Edge Cases

Borderline cases (near threshold):

⚠️ Borderline Case: 64% similarity

This is right on the edge between "High" and "Medium" similarity.

I'll present both perspectives so you can make an informed decision.

Multiple candidates with similar scores:

📊 Multiple Similar Candidates:

Button [btn-001]: 72% similarity
Button [btn-003]: 68% similarity

btn-001 is slightly closer, but both are viable options.
I'll compare to btn-001 for the decision.

Perfect match but different context:

⚠️ Unusual Pattern: 98% similarity but different context

Visually and behaviorally identical, but used in completely different contexts.

This might indicate:

- Same component, different use case ✓
- Accidental duplication ⚠️
- Context-specific variant needed 🤔

````

---

## Output Format

**For next step:**

json { "similarity": {

"percentage": 72,
"level": "high",
"level_number": 3,
"recommendation": "designer_decision",
"key_factors": [
  "Icon presence",
  "Loading state",
  "Navigation vs Submission"
]

} } ````

6. Present MENU OPTIONS

Display: "Select an Option: [C] Continue to Identify Opportunities"

Menu Handling Logic:

• IF C: Update design log, then load, read entire file, then execute {nextStepFile}
• IF Any other comments or queries: help user respond then Redisplay Menu Options

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects the appropriate option
• User can chat or ask questions — always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option is selected and similarity calculated and classified], will you then load and read fully {nextStepFile} to execute the next step.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Step goal achieved completely
• All instructions executed in sequence
• Results documented and presented to user
• User confirmed before proceeding
• Design log updated

❌ SYSTEM FAILURE:

• Skipping any instruction in the sequence
• Generating content without user input
• Jumping ahead to later steps
• Not presenting results to user
• Proceeding without user confirmation

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.