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:

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:

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:

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:

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))
        for chunk, emb in zip(self.chunks, self.embeddings)
    ]
    return sorted(scores, key=lambda x: x[1], reverse=True)[:top_k]

Strategy 3: Progressive Disclosure

Load context progressively as needed:

class ProgressiveContextLoader: """ Load context progressively based on task needs. """

def __init__(self, design_system: DesignSystem):
    self.system = design_system
    self.loaded_context = {}
    self.context_budget = 8000  # tokens

def initial_context(self) -> dict:
    """
    Minimal context for task understanding.
    ~500 tokens
    """
    return {
        "system_summary": self.system.summary,
        "available_components": list(self.system.component_names),
        "color_palette_summary": self.system.color_summary,
    }

def expand_for_component(self, component_name: str) -> dict:
    """
    Expand context when working on specific component.
    +1000-2000 tokens
    """
    if component_name in self.loaded_context:
        return self.loaded_context[component_name]

    context = {
        "component_spec": self.system.get_component(component_name),
        "related_tokens": self.system.get_tokens_for(component_name),
        "examples": self.system.get_examples(component_name, limit=2),
    }

    self.loaded_context[component_name] = context
    return context

def expand_for_layout(self) -> dict:
    """
    Expand context for layout work.
    +500 tokens
    """
    return {
        "spacing_scale": self.system.spacing,
        "breakpoints": self.system.breakpoints,
        "grid_system": self.system.grid,
        "container_widths": self.system.containers,
    }

def get_current_context(self) -> str:
    """
    Get current accumulated context within budget.
    """
    context_str = json.dumps(self.loaded_context)
    token_count = self.count_tokens(context_str)

    if token_count > self.context_budget:
        return self.prune_context(context_str)

    return context_str

Persisting Design Decisions

Decision Memory Pattern

Store and recall design decisions for consistency:

class DesignDecisionMemory: """ Persistent memory for design decisions. """

def __init__(self, project_id: str, storage: Storage):
    self.project_id = project_id
    self.storage = storage
    self.decisions = self.load_decisions()

def record_decision(self, decision: DesignDecision) -> None:
    """
    Record a design decision for future reference.
    """
    entry = {
        "id": str(uuid4()),
        "timestamp": datetime.now().isoformat(),
        "category": decision.category,  # color, spacing, component, etc.
        "component": decision.component,
        "decision": decision.description,
        "rationale": decision.rationale,
        "tokens_affected": decision.tokens,
        "embedding": self.embed(decision.description),
    }

    self.decisions.append(entry)
    self.storage.save(self.decisions)

def recall_for_context(self, current_task: str) -> list[dict]:
    """
    Recall relevant past decisions for current task.
    """
    task_embedding = self.embed(current_task)

    relevant = []
    for decision in self.decisions:
        similarity = cosine_similarity(task_embedding, decision["embedding"])
        if similarity > 0.7:
            relevant.append({
                "decision": decision["decision"],
                "rationale": decision["rationale"],
                "relevance": similarity,
            })

    return sorted(relevant, key=lambda x: x["relevance"], reverse=True)[:5]

def format_for_prompt(self, decisions: list[dict]) -> str:
    """
    Format decisions for prompt injection.
    """
    if not decisions:
        return ""

    lines = ["## Previous Design Decisions (maintain consistency):"]
    for d in decisions:
        lines.append(f"- {d['decision']}")
        if d.get("rationale"):
            lines.append(f"  Rationale: {d['rationale']}")

    return "\n".join(lines)

Usage in prompt construction

memory = DesignDecisionMemory("project-123", storage) relevant_decisions = memory.recall_for_context("Create a modal dialog")

prompt = f""" {base_prompt}

{memory.format_for_prompt(relevant_decisions)} """

Version-Controlled Context

Treat design context as versioned artifacts:

class VersionedDesignContext: """ Version-controlled design system context. """

def __init__(self, repo_path: str):
    self.repo_path = repo_path
    self.current_version = self.get_current_version()

def get_context_at_version(self, version: str) -> dict:
    """
    Load design context at specific version.
    Useful for reproducing past generations.
    """
    tokens_path = f"{self.repo_path}/tokens/{version}/tokens.json"
    components_path = f"{self.repo_path}/components/{version}/"

    return {
        "version": version,
        "tokens": self.load_json(tokens_path),
        "components": self.load_components(components_path),
    }

def diff_versions(self, v1: str, v2: str) -> dict:
    """
    Show differences between context versions.
    Useful for understanding changes.
    """
    ctx1 = self.get_context_at_version(v1)
    ctx2 = self.get_context_at_version(v2)

    return {
        "tokens_added": self.diff_tokens(ctx1["tokens"], ctx2["tokens"]),
        "tokens_changed": self.changed_tokens(ctx1["tokens"], ctx2["tokens"]),
        "components_added": self.diff_components(ctx1, ctx2),
    }

def get_migration_context(self, from_v: str, to_v: str) -> str:
    """
    Generate context for migrating components between versions.
    """
    diff = self.diff_versions(from_v, to_v)

    return f"""
    ## Design System Migration: {from_v} -> {to_v}

    ### Token Changes
    {self.format_token_changes(diff['tokens_changed'])}

    ### New Tokens
    {self.format_new_tokens(diff['tokens_added'])}

    ### Update Instructions
    When updating components, apply these token mappings...
    """

Context Window Optimization

Token Budget Allocation

Allocate context window strategically:

class ContextBudgetManager: """ Manage context window token budget. """

def __init__(self, total_budget: int = 100000):  # Claude's context
    self.total = total_budget
    self.allocations = {
        "system_prompt": 2000,    # Fixed instructions
        "design_tokens": 3000,    # Core tokens
        "component_context": 4000, # Current component
        "examples": 2000,         # Few-shot examples
        "memory": 1000,           # Past decisions
        "task": 500,              # Current request
        "output_buffer": 10000,   # Reserved for response
    }

def remaining_budget(self) -> int:
    """
    Calculate remaining tokens for dynamic content.
    """
    allocated = sum(self.allocations.values())
    return self.total - allocated

def can_load(self, content: str, category: str) -> bool:
    """
    Check if content fits in category budget.
    """
    token_count = self.count_tokens(content)
    return token_count <= self.allocations.get(category, 0)

def optimize_context(self, context: dict) -> dict:
    """
    Optimize context to fit within budget.
    """
    optimized = {}

    for key, content in context.items():
        budget = self.allocations.get(key, 1000)
        content_tokens = self.count_tokens(str(content))

        if content_tokens <= budget:
            optimized[key] = content
        else:
            optimized[key] = self.truncate_intelligently(content, budget)

    return optimized

def truncate_intelligently(self, content: any, budget: int) -> any:
    """
    Truncate content preserving most important information.
    """
    if isinstance(content, list):
        # For lists, keep first N items
        result = []
        tokens = 0
        for item in content:
            item_tokens = self.count_tokens(str(item))
            if tokens + item_tokens <= budget:
                result.append(item)
                tokens += item_tokens
        return result

    if isinstance(content, dict):
        # For dicts, prioritize by key importance
        priority_keys = ["essential", "primary", "core", "main"]
        result = {}
        tokens = 0

        # First pass: priority keys
        for key in priority_keys:
            if key in content:
                result[key] = content[key]
                tokens += self.count_tokens(str(content[key]))

        # Second pass: remaining keys if budget allows
        for key, value in content.items():
            if key not in result:
                value_tokens = self.count_tokens(str(value))
                if tokens + value_tokens <= budget:
                    result[key] = value
                    tokens += value_tokens

        return result

    # For strings, truncate with ellipsis
    return self.truncate_string(content, budget)

Context Injection Patterns

Pattern: Structured Context Block

Inject context as a structured, parseable block:

<!-- DESIGN_CONTEXT_START -->

Active Design System: Acme Design v2.3

Tokens

{
  "colors": {"primary": "#6366F1", "gray": "#6B7280"},
  "spacing": {"base": "4px", "scale": [1,2,4,6,8,12,16]},
  "radius": {"default": "8px"}
}

Component: Button

- Variants: primary, secondary, ghost, danger

- Sizes: sm (32px), md (40px), lg (48px)

- States: default, hover, focus, active, disabled, loading

Constraints

- Tailwind CSS only

- Accessibility: WCAG 2.1 AA

- Must support dark mode

### Pattern: Inline Context References

Reference context inline rather than loading fully:

```markdown
Generate a Card component.

Use these token references (from loaded design system):
- Background: `tokens.colors.surface.primary`
- Border: `tokens.colors.border.subtle`
- Padding: `tokens.spacing.lg` (maps to p-6)
- Radius: `tokens.radius.lg` (maps to rounded-xl)
- Shadow: `tokens.shadows.md` (maps to shadow-md)

The component should resolve these references to actual Tailwind classes.

Quick Reference

Challenge
Strategy

Too many tokens
Compressed Token Format

Finding relevant context
Semantic Chunking + Retrieval

Large design systems
Progressive Disclosure

Maintaining consistency
Decision Memory Pattern

Reproducing results
Version-Controlled Context

Budget constraints
Token Budget Allocation

Integration Points

This skill integrates with:

- agent-orchestration/ui-agent-patterns
 - Context for agent workflows

- llm-application-dev/prompt-engineering-ui
 - Token injection in prompts

- llm-application-dev/rag-implementation
 - Retrieval of context chunks

- mcp-integrations/browser-devtools-mcp
 - Live context from running UI

"Context is not just what the model sees - it is what the model becomes."