dss/.knowledge/DSS_CORE.json

{
  "$schema": "dss-core-v1",
  "version": "1.1.0",
  "last_updated": "2025-12-10",
  "purpose": "Single source of truth for AI agents working with DSS",

  "meta": {
    "schema_ref": "https://sofi.internal/dss/schemas/dss-core-v1.json",
    "compat": {
      "min_admin_ui": "0.6.0",
      "min_cli": "0.4.0",
      "min_mcp_server": "0.3.0"
    },
    "status": "stable",
    "owners": ["dss-core@sofi.com"],
    "tags": ["design-system", "tokens", "figma", "storybook", "mcp"]
  },

  "what_is_dss": {
    "description": "Design System Server - monolithic platform for design token management",
    "core_function": "Ingest tokens from multiple sources, normalize to canonical format, generate outputs",
    "philosophy": "DSS structure is sacred - external systems adapt TO DSS, not reverse"
  },

  "canonical_structure": {
    "tokens": ["colors", "spacing", "typography", "borders", "shadows", "motion"],
    "components": ["Button", "Input", "Card", "Badge", "Toast", "..."],
    "patterns": ["forms", "navigation", "layouts"],
    "rule": "This structure NEVER changes. All inputs normalize to this."
  },

  "key_concepts": {
    "translation_dictionaries": {
      "what": "Per-project mappings from external systems to DSS canonical tokens",
      "flow": "Source tokens -> Translation layer -> DSS canonical -> Output"
    },
    "custom_props": {
      "what": "Client-specific properties outside DSS core",
      "namespace": "color.brand.{client}.*",
      "rule": "Never modify DSS core - add to custom namespace"
    },
    "merge_strategies": {
      "FIRST": "Keep first occurrence",
      "LAST": "Override with latest",
      "PREFER_FIGMA": "Prioritize Figma source",
      "PREFER_CODE": "Prioritize CSS/SCSS",
      "PREFER_SPECIFIC": "Prefer concrete values over references",
      "MERGE_METADATA": "Combine metadata, use latest value"
    }
  },

  "architecture": {
    "layers": {
      "router": "MCP Server (36 tools), REST API (34 endpoints), CLI",
      "messaging": "Circuit breaker, Activity log, Event emitter",
      "workflows": "Figma client, Token ingestion, Storybook generator, Analysis engine, Context compiler, Storage (JSON files)"
    },
    "ports": {
      "rest_api": 3456,
      "mcp_server": 3457
    },
    "dependencies": {
      "python": ">=3.10",
      "node": ">=18",
      "services": ["figma-api", "storybook"]
    },
    "storage": {
      "type": "JSON files",
      "location": ".dss/data/",
      "structure": {
        "_system": "config, cache, activity logs",
        "projects/{id}": "manifest, tokens/, components/, styles/, figma/, metrics/",
        "teams/{id}": "manifest, members, access"
      },
      "philosophy": "Eat our own food - storage mirrors DSS canonical structure"
    }
  },

  "mcp_tools_categories": {
    "project_management": ["dss_analyze_project"],
    "token_ingestion": ["dss_extract_tokens", "dss_transform_tokens", "dss_resolve_token"],
    "utilities": ["dss_generate_theme", "dss_list_themes", "dss_get_status", "dss_find_quick_wins", "dss_validate_manifest", "dss_list_skins"],
    "analysis": ["dss_audit_components", "browser_accessibility_audit"],
    "storybook": ["dss_setup_storybook"],
    "figma_integration": ["dss_sync_figma"],
    "browser_tools": ["devtools_launch", "devtools_connect", "devtools_console_logs", "devtools_screenshot", "..."],
    "context_compiler": ["dss_get_resolved_context", "dss_get_compiler_status"]
  },

  "context_compiler": {
    "cascade": "Base Skin -> Extended Skin -> Project Overrides = Final Context",
    "caching": "mtime-based invalidation",
    "security": "Path traversal prevention, input validation",
    "lifecycle": {
      "states": ["idle", "building", "ready", "stale", "error"],
      "transitions": {
        "idle->building": "trigger build",
        "building->ready": "build success",
        "ready->stale": "source mtime changed",
        "any->error": "uncaught exception"
      }
    }
  },

  "file_paths": {
    "mcp_server": "dss-claude-plugin/servers/dss-mcp-server.py",
    "rest_api": "tools/api/server.py",
    "token_parsers": "tools/ingest/",
    "analysis": "tools/analyze/",
    "storage": "tools/storage/json_store.py",
    "data": ".dss/data/",
    "schemas": ".dss/schema/",
    "admin_ui": "admin-ui/",
    "skills": "dss-claude-plugin/skills/",
    "commands": "dss-claude-plugin/commands/",
    "logs": ".dss/logs/",
    "cache": ".dss/cache/"
  },

  "coding_rules_summary": {
    "web_components": "Shadow DOM required, lifecycle management, data-action event delegation",
    "styles": "No inline styles, use CSS custom properties",
    "events": "No inline handlers, use data-action pattern",
    "accessibility": "WCAG 2.1 AA, semantic HTML, ARIA attributes",
    "state": "Context store for global, component state for local, no direct DOM manipulation",
    "errors": "Use logger utility, structured error codes (E1xxx-E5xxx, S1xxx)"
  },

  "error_codes": {
    "E1xxx": "User errors",
    "E2xxx": "Validation errors",
    "E3xxx": "API errors",
    "E4xxx": "System errors",
    "E5xxx": "Integration errors",
    "S1xxx": "Success codes"
  },

  "supported_sources": {
    "tokens": ["Figma", "CSS", "SCSS", "Tailwind", "JSON"],
    "output_formats": ["CSS", "SCSS", "JSON", "JS", "Storybook theme"]
  },

  "capabilities": {
    "ingestion": ["figma", "css", "scss", "tailwind", "json"],
    "normalization": ["resolve references", "merge metadata", "de-duplicate"],
    "generation": ["css vars", "scss maps", "json manifests", "storybook themes"],
    "analysis": ["component audit", "accessibility audit", "quick wins"],
    "integration": ["mcp tools", "rest api", "cli", "admin-ui"],
    "governance": ["translation dictionaries", "custom namespaces", "merge strategies"]
  },

  "interfaces": {
    "rest": {
      "base": "/api/v1",
      "endpoints": [
        {"path": "/tokens/ingest", "method": "POST", "desc": "Ingest tokens"},
        {"path": "/tokens/export", "method": "GET", "desc": "Export normalized tokens"},
        {"path": "/context", "method": "GET", "desc": "Resolved context"},
        {"path": "/themes", "method": "GET", "desc": "List available themes"}
      ]
    },
    "cli": {
      "commands": ["dss ingest", "dss generate", "dss analyze", "dss context"]
    },
    "events": {
      "emitted": ["ingestion.completed", "context.ready", "theme.generated", "audit.completed"],
      "subscribed": ["figma.sync", "repo.changed", "cache.invalidate"]
    }
  },

  "metrics": {
    "ingestion_time_ms": {"p50": 500, "p95": 2000},
    "context_build_ms": {"p50": 800, "p95": 2500},
    "cache_hit_rate": {"target": 0.8},
    "error_rate": {"target": 0.01}
  },

  "security": {
    "input_validation": true,
    "path_sanitization": true,
    "allowed_sources": ["figma", "filesystem", "repo"],
    "secrets": {
      "env": ["FIGMA_TOKEN", "STORYBOOK_TOKEN"],
      "store": "keychain (macOS) or env"
    }
  },

  "governance": {
    "change_control": "PR required for canonical changes",
    "reviewers": ["design-systems", "frontend-arch"],
    "versioning": {
      "core": "semver",
      "tokens": "schema-tagged versions",
      "skins": "named releases"
    }
  },

  "validation": {
    "schema_checks": ["tokens.json schema", "theme.json schema"],
    "lint": ["naming conventions", "namespace rules"],
    "tests": ["ingestion", "merge", "context"]
  },

  "operational": {
    "logging": {
      "level": "info",
      "path": ".dss/logs/dss.log"
    },
    "performance": {
      "max_workers": 4,
      "debounce_ms": 250
    },
    "storage": {
      "data": ".dss/data/",
      "cache": ".dss/data/_system/cache/"
    }
  },

  "examples": {
    "custom_namespace": "color.brand.acme.primary",
    "merge_strategy": "PREFER_FIGMA",
    "cli": "dss ingest --source figma --file tokens.json"
  },

  "changelog": [
    {"version": "1.1.0", "date": "2025-12-10", "notes": "Migrate from SQLite to JSON file storage"},
    {"version": "1.0.0", "date": "2025-12-10", "notes": "Initial core definition"}
  ]
}