docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,574 @@
|
||||
---
|
||||
name: 'step-08d-add-variant'
|
||||
description: 'Add a new variant to an existing component in the design system'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-08e-generate-catalog.md'
|
||||
---
|
||||
|
||||
# Step 8d: Add Variant
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Add a new variant to an existing component: extract variant-specific info, determine name, update component file, track usage, validate addition.
|
||||
|
||||
## 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)
|
||||
|
||||
## Step 1: Load Existing Component
|
||||
|
||||
<action>
|
||||
Read existing component file:
|
||||
- Component ID
|
||||
- Current variants
|
||||
- Shared attributes
|
||||
- Variant-specific attributes
|
||||
</action>
|
||||
|
||||
**Example:**
|
||||
|
||||
```yaml
|
||||
Component: Button [btn-001]
|
||||
Current Variants:
|
||||
- primary (submit actions)
|
||||
- secondary (cancel actions)
|
||||
```
|
||||
|
||||
<output>
|
||||
```
|
||||
📖 Loaded Button [btn-001]
|
||||
|
||||
Current variants: 2 (primary, secondary)
|
||||
Adding new variant: navigation
|
||||
|
||||
````
|
||||
</output>
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Extract Variant-Specific Information
|
||||
|
||||
<action>
|
||||
From new component specification, extract:
|
||||
- What's different from existing variants?
|
||||
- What's shared with existing variants?
|
||||
- Variant-specific styling
|
||||
- Variant-specific behaviors
|
||||
- Variant-specific states (if any)
|
||||
</action>
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
Shared with existing:
|
||||
- Size: medium
|
||||
- Shape: rounded
|
||||
- Base states: default, hover, active, disabled
|
||||
|
||||
Different from existing:
|
||||
- Has icon (arrow-right)
|
||||
- Has loading state
|
||||
- Icon animation on hover
|
||||
- Purpose: navigation vs submission
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Determine Variant Name
|
||||
|
||||
<action>
|
||||
Generate descriptive variant name:
|
||||
- Based on purpose or visual distinction
|
||||
- Consistent with existing variant naming
|
||||
- Clear and semantic
|
||||
</action>
|
||||
|
||||
**Examples:**
|
||||
|
||||
```
|
||||
Purpose-based:
|
||||
- navigation (for navigation actions)
|
||||
- destructive (for delete/remove actions)
|
||||
- success (for positive confirmations)
|
||||
|
||||
Visual-based:
|
||||
- outlined (border, no fill)
|
||||
- ghost (transparent background)
|
||||
- large (bigger size)
|
||||
|
||||
Context-based:
|
||||
- header (used in headers)
|
||||
- footer (used in footers)
|
||||
- inline (used inline with text)
|
||||
```
|
||||
|
||||
<ask>
|
||||
```
|
||||
Suggested variant name: "navigation"
|
||||
|
||||
This variant is for navigation actions (continue, next, proceed).
|
||||
|
||||
Is this name clear and appropriate? (y/n)
|
||||
Or suggest alternative name:
|
||||
|
||||
````
|
||||
</ask>
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Update Component File
|
||||
|
||||
<action>
|
||||
Add variant to component definition:
|
||||
</action>
|
||||
|
||||
### Update Variants Section
|
||||
|
||||
**Before:**
|
||||
```markdown
|
||||
## Variants
|
||||
|
||||
- **primary** - Main call-to-action (submit, save, continue)
|
||||
- **secondary** - Secondary actions (cancel, back)
|
||||
````
|
||||
|
||||
**After:**
|
||||
|
||||
```markdown
|
||||
## Variants
|
||||
|
||||
- **primary** - Main call-to-action (submit, save, continue)
|
||||
- **secondary** - Secondary actions (cancel, back)
|
||||
- **navigation** - Navigation actions (next, proceed, continue) ← Added
|
||||
```
|
||||
|
||||
### Add Variant-Specific Styling
|
||||
|
||||
**Add section:**
|
||||
|
||||
```markdown
|
||||
### Variant-Specific Styling
|
||||
|
||||
**Primary:**
|
||||
|
||||
- Background: blue-600
|
||||
- Icon: none
|
||||
- Loading: spinner only
|
||||
|
||||
**Secondary:**
|
||||
|
||||
- Background: gray-200
|
||||
- Text: gray-900
|
||||
- Icon: none
|
||||
|
||||
**Navigation:** ← Added
|
||||
|
||||
- Background: blue-600
|
||||
- Icon: arrow-right
|
||||
- Loading: spinner + icon
|
||||
- Hover: icon shifts right
|
||||
```
|
||||
|
||||
### Update States (if variant has unique states)
|
||||
|
||||
**If navigation variant has loading state but others don't:**
|
||||
|
||||
```markdown
|
||||
## States
|
||||
|
||||
**Shared States (all variants):**
|
||||
|
||||
- default
|
||||
- hover
|
||||
- active
|
||||
- disabled
|
||||
|
||||
**Variant-Specific States:**
|
||||
|
||||
**Navigation:**
|
||||
|
||||
- loading (shows spinner, disables interaction)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Update Usage Tracking
|
||||
|
||||
<action>
|
||||
Track new variant usage:
|
||||
</action>
|
||||
|
||||
**Add to component file:**
|
||||
|
||||
```markdown
|
||||
## Variant Usage
|
||||
|
||||
**Primary:** 5 pages
|
||||
**Secondary:** 3 pages
|
||||
**Navigation:** 1 page ← Added
|
||||
|
||||
**Navigation variant used in:**
|
||||
|
||||
- Onboarding page (continue button)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Update Component Complexity Note
|
||||
|
||||
<action>
|
||||
Add note about variant count:
|
||||
</action>
|
||||
|
||||
**If this is 3rd+ variant:**
|
||||
|
||||
```markdown
|
||||
## Notes
|
||||
|
||||
This component now has 3 variants. Consider:
|
||||
|
||||
- Are all variants necessary?
|
||||
- Should any variants be separate components?
|
||||
- Is the component becoming too complex?
|
||||
|
||||
Review component organization when reaching 5+ variants.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Validate Variant Addition
|
||||
|
||||
<action>
|
||||
Check for potential issues:
|
||||
</action>
|
||||
|
||||
**Variant Explosion Check:**
|
||||
|
||||
```
|
||||
⚠️ Variant Count: 3
|
||||
|
||||
This is manageable. Monitor for variant explosion as more are added.
|
||||
|
||||
Recommended maximum: 5 variants per component
|
||||
```
|
||||
|
||||
**Consistency Check:**
|
||||
|
||||
```
|
||||
✓ New variant consistent with existing variants
|
||||
✓ Naming convention followed
|
||||
✓ Shared attributes maintained
|
||||
```
|
||||
|
||||
**Complexity Check:**
|
||||
|
||||
```
|
||||
⚠️ Navigation variant adds loading state not present in other variants.
|
||||
|
||||
This increases component complexity. Consider:
|
||||
- Should loading state be shared across all variants?
|
||||
- Or is it truly navigation-specific?
|
||||
|
||||
Current approach: Variant-specific (acceptable)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Update Component Version
|
||||
|
||||
<action>
|
||||
Track component changes:
|
||||
</action>
|
||||
|
||||
**Update version history:**
|
||||
|
||||
```markdown
|
||||
## Version History
|
||||
|
||||
**Created:** 2024-12-01
|
||||
**Last Updated:** 2024-12-09
|
||||
|
||||
**Changes:**
|
||||
|
||||
- 2024-12-01: Created component with primary and secondary variants
|
||||
- 2024-12-09: Added navigation variant ← Added
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Create Component Reference
|
||||
|
||||
<action>
|
||||
Generate reference for page spec:
|
||||
</action>
|
||||
|
||||
**Output:**
|
||||
|
||||
```yaml
|
||||
component_reference:
|
||||
id: btn-001
|
||||
name: Button
|
||||
variant: navigation ← New variant
|
||||
file: D-Design-System/components/button.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 10: Complete
|
||||
|
||||
<output>
|
||||
```
|
||||
✅ Variant Added: Button.navigation [btn-001]
|
||||
|
||||
Component: Button [btn-001]
|
||||
New Variant: navigation
|
||||
Total Variants: 3 (primary, secondary, navigation)
|
||||
|
||||
Component file updated:
|
||||
|
||||
- Variant added to list
|
||||
- Variant-specific styling documented
|
||||
- Usage tracking added
|
||||
- Version history updated
|
||||
|
||||
Reference ready for page spec.
|
||||
|
||||
Next: Return to Phase 4 to complete page specification
|
||||
|
||||
```
|
||||
</output>
|
||||
|
||||
---
|
||||
|
||||
## Designer Guidance
|
||||
|
||||
<output>
|
||||
```
|
||||
|
||||
💡 Variant Management Tips:
|
||||
|
||||
**Current Status:**
|
||||
|
||||
- Component: Button [btn-001]
|
||||
- Variants: 3
|
||||
- Status: Healthy
|
||||
|
||||
**Watch for:**
|
||||
|
||||
- 5+ variants → Consider splitting component
|
||||
- Variants with very different purposes → Might need separate components
|
||||
- Variants rarely used together → Might indicate separate components
|
||||
|
||||
**Best Practices:**
|
||||
|
||||
- Keep variants related (same base purpose)
|
||||
- Use clear, semantic variant names
|
||||
- Document when to use each variant
|
||||
- Review variant list periodically
|
||||
|
||||
You can always refactor later if needed!
|
||||
|
||||
```
|
||||
</output>
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
<action>
|
||||
Validate variant addition:
|
||||
- ✓ Variant added to component file
|
||||
- ✓ Variant-specific attributes documented
|
||||
- ✓ Usage tracking updated
|
||||
- ✓ Version history updated
|
||||
- ✓ Reference generated
|
||||
- ✓ Complexity checked
|
||||
</action>
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**If variant name conflicts:**
|
||||
```
|
||||
|
||||
⚠️ Variant "navigation" already exists in Button [btn-001].
|
||||
|
||||
This might mean:
|
||||
|
||||
1. You're trying to add a duplicate
|
||||
2. The existing variant should be updated
|
||||
3. A different variant name is needed
|
||||
|
||||
Current navigation variant:
|
||||
[Show existing variant details]
|
||||
|
||||
Options:
|
||||
|
||||
1. Update existing variant
|
||||
2. Choose different name
|
||||
3. Cancel
|
||||
|
||||
Your choice:
|
||||
|
||||
```
|
||||
|
||||
**If component file not found:**
|
||||
```
|
||||
|
||||
❌ Error: Component file not found.
|
||||
|
||||
Component ID: btn-001
|
||||
Expected file: D-Design-System/components/button.md
|
||||
|
||||
This shouldn't happen. Possible causes:
|
||||
|
||||
- File was deleted
|
||||
- Component ID is incorrect
|
||||
- Design system structure corrupted
|
||||
|
||||
Would you like to:
|
||||
|
||||
1. Create component as new
|
||||
2. Specify correct component ID
|
||||
3. Cancel
|
||||
|
||||
Your choice:
|
||||
|
||||
```
|
||||
|
||||
**If variant too different:**
|
||||
```
|
||||
|
||||
⚠️ Warning: High Divergence Detected
|
||||
|
||||
The new variant is very different from existing variants:
|
||||
|
||||
- Different core purpose
|
||||
- Different visual structure
|
||||
- Different behavioral patterns
|
||||
|
||||
Similarity to existing variants: 35%
|
||||
|
||||
This might be better as a separate component.
|
||||
|
||||
Options:
|
||||
|
||||
1. Add as variant anyway
|
||||
2. Create as new component instead
|
||||
3. Review differences in detail
|
||||
|
||||
Your choice:
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Post-Addition Review
|
||||
|
||||
<action>
|
||||
After adding variant, check component health:
|
||||
</action>
|
||||
|
||||
**Component Health Check:**
|
||||
```
|
||||
|
||||
📊 Component Health: Button [btn-001]
|
||||
|
||||
Variants: 3
|
||||
Complexity: Medium
|
||||
Consistency: High
|
||||
Usage: 9 pages
|
||||
|
||||
Health Status: ✅ Healthy
|
||||
|
||||
Recommendations:
|
||||
|
||||
- Document variant selection guidelines
|
||||
- Consider adding variant usage examples
|
||||
- Monitor for variant explosion
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**This operation adds a variant. Return to Phase 4 with component reference.**
|
||||
```
|
||||
|
||||
### 11. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [C] Continue to Generate Catalog or [M] Return to Activity Menu"
|
||||
|
||||
#### 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](#11-present-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 [variant is added, component file updated, and usage tracked], 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.
|
||||
Reference in New Issue
Block a user