dss/examples/README.md

DSS Code Examples

Practical examples showing how to use DSS core functionality.

Running the Examples

# 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 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

#!/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

try:
    result = await some_operation()
    print(f"✅ Success: {result}")
except Exception as e:
    print(f"❌ Error: {e}")

Need Help?

• Read QUICKSTART.md for detailed guides
• Check ARCHITECTURE.md for system design
• Review PROJECT_MEMORY.md for module inventory