276ed71f31
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
114 lines
2.5 KiB
Markdown
114 lines
2.5 KiB
Markdown
# DSS Code Examples
|
|
|
|
Practical examples showing how to use DSS core functionality.
|
|
|
|
## Running the Examples
|
|
|
|
```bash
|
|
# Activate virtual environment
|
|
source .venv/bin/activate
|
|
|
|
# Run any example
|
|
python examples/01_basic_ingestion.py
|
|
python examples/02_token_merge.py
|
|
python examples/03_project_analysis.py
|
|
```
|
|
|
|
## Example List
|
|
|
|
### 01_basic_ingestion.py
|
|
**Topic**: Token Ingestion from Multiple Sources
|
|
|
|
Shows how to extract design tokens from:
|
|
- CSS custom properties (`:root { --var: value; }`)
|
|
- SCSS variables (`$var: value;`)
|
|
- JSON tokens (W3C Design Tokens format)
|
|
|
|
**Output**: Demonstrates token extraction with counts and preview
|
|
|
|
---
|
|
|
|
### 02_token_merge.py
|
|
**Topic**: Merging Tokens with Conflict Resolution
|
|
|
|
Shows how to:
|
|
- Create token collections from different sources
|
|
- Merge tokens using different strategies (FIRST, LAST, PREFER_FIGMA)
|
|
- Resolve conflicts between sources
|
|
- Understand which strategy to use when
|
|
|
|
**Output**: Side-by-side comparison of merge strategies and conflict resolution
|
|
|
|
---
|
|
|
|
### 03_project_analysis.py
|
|
**Topic**: Project Analysis & Quick Wins
|
|
|
|
Shows how to:
|
|
- Scan a project for framework and styling detection
|
|
- Find improvement opportunities (quick wins)
|
|
- Prioritize changes by impact vs effort
|
|
- Generate improvement reports
|
|
|
|
**Output**: Project stats, quick win recommendations, prioritized task list
|
|
|
|
---
|
|
|
|
## More Examples
|
|
|
|
Check the [QUICKSTART.md](../docs/QUICKSTART.md) for:
|
|
- Full workflow examples (Figma → DSS → Storybook)
|
|
- REST API usage
|
|
- MCP tool integration
|
|
- Production deployment patterns
|
|
|
|
## Adding Your Own Examples
|
|
|
|
1. Create a new file: `examples/XX_your_example.py`
|
|
2. Add docstring explaining the example
|
|
3. Use `async def main()` pattern
|
|
4. Add to this README
|
|
5. Submit PR!
|
|
|
|
## Common Patterns
|
|
|
|
### Basic Example Structure
|
|
|
|
```python
|
|
#!/usr/bin/env python3
|
|
"""Brief description of what this example demonstrates"""
|
|
|
|
import asyncio
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
# Add project to path
|
|
sys.path.insert(0, str(Path(__file__).parent.parent))
|
|
|
|
async def main():
|
|
print("=" * 60)
|
|
print("EXAMPLE TITLE")
|
|
print("=" * 60)
|
|
|
|
# Your code here
|
|
|
|
if __name__ == "__main__":
|
|
asyncio.run(main())
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
```python
|
|
try:
|
|
result = await some_operation()
|
|
print(f"✅ Success: {result}")
|
|
except Exception as e:
|
|
print(f"❌ Error: {e}")
|
|
```
|
|
|
|
## Need Help?
|
|
|
|
- Read [QUICKSTART.md](../docs/QUICKSTART.md) for detailed guides
|
|
- Check [ARCHITECTURE.md](../docs/ARCHITECTURE.md) for system design
|
|
- Review [PROJECT_MEMORY.md](../PROJECT_MEMORY.md) for module inventory
|