{
  "$schema": "dss-knowledge-v1",
  "type": "principles",
  "version": "1.0.0",
  "last_updated": "2025-12-07",
  "core_principles": [
    {
      "name": "Monolithic Design System Structure",
      "description": "DSS defines THE canonical design system structure. It does not change.",
      "structure": {
        "tokens": ["colors", "spacing", "typography", "borders", "shadows", "motion"],
        "components": ["Button", "Input", "Card", "..."],
        "patterns": ["forms", "navigation", "layouts"]
      },
      "rule": "This structure is sacred. External systems adapt to us, not the reverse."
    },
    {
      "name": "Translation Dictionaries (Per-Project)",
      "description": "Each client project maintains a Translation Dictionary that maps their legacy tokens/styles to DSS canonical tokens",
      "schema": "dss-translation-v1",
      "mapping_types": ["tokens", "components", "patterns"],
      "custom_props_namespace": "Isolated namespace for client-specific properties"
    },
    {
      "name": "Custom Props Strategy",
      "description": "When a client needs something outside DSS core",
      "rules": [
        "Never modify DSS core - The canonical structure stays intact",
        "Add to project's custom namespace - color.brand.{client}.*",
        "Create Storybook template for custom case",
        "Document in translation dictionary"
      ]
    },
    {
      "name": "Multi-System Ingestion Flow",
      "description": "All external systems translate TO DSS canonical format",
      "sources": ["Figma", "Legacy CSS", "shadcn", "HeroUI", "Tailwind"],
      "flow": [
        "Source tokens extracted",
        "Translation layer maps to DSS canonical",
        "Custom props identified and isolated",
        "Mappings stored in translation dictionary",
        "DSS core (immutable) + Project custom props",
        "Output: Storybook, token files, component library"
      ]
    },
    {
      "name": "Storybook Strategy",
      "description": "Separate core stories from client-specific stories",
      "structure": {
        "core": "DSS canonical components (never modified)",
        "clients": "Custom variations in /stories/clients/{client}/",
        "templates": "Edge cases, specific customizations"
      }
    },
    {
      "name": "Component Extension Model",
      "description": "Clients extend/wrap DSS components, never modify core",
      "pattern": "Client wraps DSS component with additional props",
      "example": "AcmeButton extends Button with acmeIcon, acmeTracking props"
    },
    {
      "name": "Token Merge System",
      "description": "Intelligent token merging from multiple sources with conflict resolution",
      "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"
      ]
    },
    {
      "name": "UI Library Atomic Structure Comparison",
      "description": "Different UI libraries use fundamentally different atomic structures. DSS normalizes them all",
      "comparisons": {
        "HeroUI": {
          "color_system": "Numeric scales (50-900)",
          "granularity": "HIGH (10 shades)",
          "translation": "Direct 1:1 mapping, strip prefix"
        },
        "shadcn": {
          "color_system": "Semantic pairs",
          "granularity": "LOW (2 values)",
          "translation": "Expand semantic to scale"
        },
        "Legacy_CSS": {
          "color_system": "Inconsistent",
          "granularity": "VARIES",
          "translation": "Normalize chaos to canonical format"
        }
      }
    }
  ],
  "translation_dictionary_schema": {
    "$schema": "dss-translation-v1",
    "required_fields": ["project", "source", "mappings"],
    "optional_fields": ["version", "custom_props", "unmapped", "notes"],
    "mapping_structure": {
      "tokens": "source-token -> dss-canonical-token",
      "components": "source-component -> dss-component[variant]",
      "patterns": "source-pattern -> dss-pattern"
    }
  }
}