# 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