design-system-context

What this skill does

# Design System Context Management

Master the art of managing design system context for LLM-driven UI development. This skill covers strategies for loading design tokens, persisting decisions, and optimizing context window usage.

---

## When to Use This Skill

- Loading design tokens into LLM context efficiently
- Persisting design decisions across sessions
- Optimizing context window for large design systems
- Managing multiple design system variants
- Building context-aware UI generation pipelines
- Maintaining consistency across agent conversations

---

## The Context Challenge

Design systems contain vast amounts of information:
- **Design tokens**: Colors, spacing, typography, shadows, etc.
- **Component specs**: 50-200+ components with variants
- **Usage guidelines**: Do's, don'ts, examples
- **Brand guidelines**: Voice, imagery, personality

**The Problem**: Context windows are finite. Loading everything wastes tokens and degrades performance.

**The Solution**: Strategic context management - load what's needed, when it's needed.

---

## Context Architecture

### Layered Context Model

Organize design system context in layers of specificity:

```
Layer 4: Task-Specific Context (highest priority)
         ↑
Layer 3: Component Context
         ↑
Layer 2: Design Token Context
         ↑
Layer 1: Brand/System Context (foundation)
```

**Implementation**:

```python
class DesignSystemContext:
    """
    Layered context management for design systems.
    """

    def __init__(self, system_name: str):
        self.layers = {
            "brand": self.load_brand_context(),      # ~500 tokens
            "tokens": self.load_design_tokens(),     # ~2000 tokens
            "components": {},                         # On-demand
            "task": {},                               # Per-request
        }

    def load_brand_context(self) -> dict:
        """
        Layer 1: Foundational brand context.
        Always loaded, rarely changes.
        """
        return {
            "brand_name": "Acme Corp",
            "brand_voice": "Professional, approachable, confident",
            "core_values": ["Simplicity", "Trust", "Innovation"],
            "color_philosophy": "Blue conveys trust, accent sparingly",
            "typography_philosophy": "Clean sans-serif, generous line-height",
        }

    def load_design_tokens(self) -> dict:
        """
        Layer 2: Design tokens.
        Loaded per session, reference frequently.
        """
        return {
            "colors": {
                "primary": {"50": "#EEF2FF", "500": "#6366F1", "900": "#312E81"},
                "gray": {"50": "#F9FAFB", "500": "#6B7280", "900": "#111827"},
                "success": "#10B981",
                "warning": "#F59E0B",
                "error": "#EF4444",
            },
            "spacing": {
                "0": "0", "1": "0.25rem", "2": "0.5rem",
                "4": "1rem", "6": "1.5rem", "8": "2rem",
            },
            "typography": {
                "font_family": "Inter, system-ui, sans-serif",
                "sizes": {"xs": "0.75rem", "sm": "0.875rem", "base": "1rem"},
                "weights": {"normal": 400, "medium": 500, "bold": 700},
            },
            "radius": {"sm": "0.25rem", "md": "0.375rem", "lg": "0.5rem"},
            "shadows": {
                "sm": "0 1px 2px rgba(0,0,0,0.05)",
                "md": "0 4px 6px rgba(0,0,0,0.1)",
            },
        }

    def load_component_context(self, component_name: str) -> dict:
        """
        Layer 3: Component-specific context.
        Loaded on-demand when working on specific components.
        """
        component_docs = self.fetch_component_docs(component_name)
        return {
            "specification": component_docs.spec,
            "variants": component_docs.variants,
            "props": component_docs.props,
            "examples": component_docs.examples[:3],  # Limit examples
            "related_components": component_docs.related[:5],
        }

    def set_task_context(self, task: dict) -> None:
        """
        Layer 4: Task-specific context.
        Fresh per request, highest priority.
        """
        self.layers["task"] = {
            "objective": task.get("objective"),
            "constraints": task.get("constraints", []),
            "preferences": task.get("preferences", {}),
            "previous_decisions": task.get("decisions", []),
        }
```

---

## Token-Efficient Context Strategies

### Strategy 1: Compressed Token Format

Reduce verbosity while maintaining meaning:

```python
# Verbose format (~200 tokens)
verbose_tokens = """
The primary color palette consists of:
- Primary 50 (lightest): #EEF2FF, used for backgrounds
- Primary 100: #E0E7FF
- Primary 200: #C7D2FE
- Primary 500 (base): #6366F1, used for primary actions
- Primary 600: #4F46E5
- Primary 900 (darkest): #312E81, used for text on light
"""

# Compressed format (~50 tokens)
compressed_tokens = """
colors.primary: {50:#EEF2FF(bg), 500:#6366F1(action), 900:#312E81(text)}
"""

# Ultra-compressed format (~20 tokens)
ultra_compressed = "pri:#6366F1 bg:#EEF2FF txt:#312E81"
```

**Compression Techniques**:

```python
class TokenCompressor:
    """
    Compress design tokens for efficient context usage.
    """

    def compress_colors(self, colors: dict) -> str:
        """
        Compress color palette to essential values.
        Only include: 50 (light), 500 (base), 900 (dark)
        """
        essential = {}
        for name, shades in colors.items():
            essential[name] = {
                k: v for k, v in shades.items()
                if k in ["50", "500", "900"]
            }
        return json.dumps(essential, separators=(",", ":"))

    def compress_spacing(self, spacing: dict) -> str:
        """
        Compress spacing to pattern description.
        """
        # Instead of listing all values
        return "spacing: 4px base unit, scale: 1,2,4,6,8,12,16,24,32"

    def compress_typography(self, typography: dict) -> str:
        """
        Compress typography to essentials.
        """
        return f"font:{typography['font_family'].split(',')[0]} sizes:xs/sm/base/lg/xl"
```

---

### Strategy 2: Semantic Chunking

Split context into semantic chunks for retrieval:

```python
class SemanticContextChunks:
    """
    Organize design system into retrievable semantic chunks.
    """

    def __init__(self, design_system: dict):
        self.chunks = self.create_chunks(design_system)
        self.embeddings = self.embed_chunks()

    def create_chunks(self, system: dict) -> list[dict]:
        """
        Create semantic chunks from design system.
        """
        chunks = []

        # Color chunks
        chunks.append({
            "type": "colors",
            "category": "primary",
            "description": "Primary brand colors for actions and emphasis",
            "content": system["tokens"]["colors"]["primary"],
        })

        chunks.append({
            "type": "colors",
            "category": "semantic",
            "description": "Semantic colors for feedback states",
            "content": {
                "success": system["tokens"]["colors"]["success"],
                "warning": system["tokens"]["colors"]["warning"],
                "error": system["tokens"]["colors"]["error"],
            },
        })

        # Component chunks
        for component in system["components"]:
            chunks.append({
                "type": "component",
                "category": component["category"],
                "description": component["description"],
                "content": component["spec"],
            })

        return chunks

    def retrieve_relevant(self, query: str, top_k: int = 5) -> list[dict]:
        """
        Retrieve chunks relevant to the current task.
        """
        query_embedding = self.embed(query)
        scores = [
            (chunk, cosine_similarity(query_embedding, emb))