{
  "$schema": "https://tr.designtokens.org/format/",
  "name": "string - Token set name",
  "description": "string - Token set description",

  "color": {
    "background": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" }, "$description": "optional" },
    "foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
    "card": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
    "card-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
    "border": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
    "input": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
    "ring": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },

    "interactive": {
      "primary": {
        "default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "disabled": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
      },
      "secondary": {
        "_comment": "Same structure as primary",
        "default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "disabled": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
      },
      "accent": {
        "_comment": "Same structure (no disabled state)",
        "default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
      },
      "destructive": {
        "_comment": "Same structure (no active/disabled states)",
        "default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
        "foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
      }
    },

    "muted": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
    "muted-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },

    "chart": {
      "1": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "2": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "3": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "4": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "5": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
    },

    "sidebar": {
      "background": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "primary": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "primary-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "accent": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "accent-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "border": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
      "ring": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
    }
  },

  "typography": {
    "font_families": {
      "sans": "string - 'Font Name', fallback1, fallback2",
      "serif": "string",
      "mono": "string"
    },
    "font_sizes": {
      "xs": "0.75rem",
      "sm": "0.875rem",
      "base": "1rem",
      "lg": "1.125rem",
      "xl": "1.25rem",
      "2xl": "1.5rem",
      "3xl": "1.875rem",
      "4xl": "2.25rem"
    },
    "line_heights": {
      "tight": "number",
      "normal": "number",
      "relaxed": "number"
    },
    "letter_spacing": {
      "tight": "string",
      "normal": "string",
      "wide": "string"
    },
    "combinations": [
      {
        "name": "h1|h2|h3|h4|h5|h6|body|caption",
        "font_family": "sans|serif|mono",
        "font_size": "string - reference to font_sizes",
        "font_weight": "number - 400|500|600|700",
        "line_height": "string",
        "letter_spacing": "string"
      }
    ]
  },

  "spacing": {
    "0": "0",
    "1": "0.25rem",
    "2": "0.5rem",
    "3": "0.75rem",
    "4": "1rem",
    "6": "1.5rem",
    "8": "2rem",
    "12": "3rem",
    "16": "4rem",
    "20": "5rem",
    "24": "6rem",
    "32": "8rem",
    "40": "10rem",
    "48": "12rem",
    "56": "14rem",
    "64": "16rem"
  },

  "opacity": {
    "disabled": "0.5",
    "hover": "0.8",
    "active": "1"
  },

  "shadows": {
    "2xs": "string - CSS shadow value",
    "xs": "string",
    "sm": "string",
    "DEFAULT": "string",
    "md": "string",
    "lg": "string",
    "xl": "string",
    "2xl": "string"
  },

  "border_radius": {
    "sm": "string - calc() or fixed",
    "md": "string",
    "lg": "string",
    "xl": "string",
    "DEFAULT": "string"
  },

  "breakpoints": {
    "sm": "640px",
    "md": "768px",
    "lg": "1024px",
    "xl": "1280px",
    "2xl": "1536px"
  },

  "component": {
    "_comment_pattern": "COMPONENT PATTERN - Apply to: button, card, input, dialog, dropdown, toast, accordion, tabs, switch, checkbox, badge, alert",
    "_example_button": {
      "$type": "component",
      "base": {
        "_comment": "Layout properties using camelCase",
        "display": "inline-flex|flex|block",
        "alignItems": "center",
        "borderRadius": "{border_radius.md}",
        "transition": "{transitions.default}"
      },
      "size": {
        "small": { "height": "32px", "padding": "{spacing.2} {spacing.3}", "fontSize": "{typography.font_sizes.xs}" },
        "default": { "height": "40px", "padding": "{spacing.2} {spacing.4}" },
        "large": { "height": "48px", "padding": "{spacing.3} {spacing.6}", "fontSize": "{typography.font_sizes.base}" }
      },
      "variant": {
        "variantName": {
          "default": { "backgroundColor": "{color.interactive.primary.default}", "color": "{color.interactive.primary.foreground}" },
          "hover": { "backgroundColor": "{color.interactive.primary.hover}" },
          "active": { "backgroundColor": "{color.interactive.primary.active}" },
          "disabled": { "backgroundColor": "{color.interactive.primary.disabled}", "opacity": "{opacity.disabled}", "cursor": "not-allowed" },
          "focus": { "outline": "2px solid {color.ring}", "outlineOffset": "2px" }
        }
      },
      "state": {
        "_comment": "For stateful components (dialog, accordion, etc.)",
        "open": { "animation": "{animation.name.component-open} {animation.duration.normal} {animation.easing.ease-out}" },
        "closed": { "animation": "{animation.name.component-close} {animation.duration.normal} {animation.easing.ease-in}" }
      }
    }
  },

  "elevation": {
    "$type": "elevation",
    "base": { "$value": "0" },
    "overlay": { "$value": "40" },
    "dropdown": { "$value": "50" },
    "dialog": { "$value": "50" },
    "tooltip": { "$value": "60" }
  },

  "_metadata": {
    "version": "string - W3C version or custom version",
    "created": "ISO timestamp - 2024-01-01T00:00:00Z",
    "source": "code-import|explore|text",
    "theme_colors_guide": {
      "description": "Theme colors are the core brand identity colors that define the visual hierarchy and emotional tone of the design system",
      "primary": {
        "role": "Main brand color",
        "usage": "Primary actions (CTAs, key interactive elements, navigation highlights, primary buttons)",
        "contrast_requirement": "WCAG AA - 4.5:1 for text, 3:1 for UI components"
      },
      "secondary": {
        "role": "Supporting brand color",
        "usage": "Secondary actions and complementary elements (less prominent buttons, secondary navigation, supporting features)",
        "principle": "Should complement primary without competing for attention"
      },
      "accent": {
        "role": "Highlight color for emphasis",
        "usage": "Attention-grabbing elements used sparingly (badges, notifications, special promotions, highlights)",
        "principle": "Should create strong visual contrast to draw focus"
      },
      "destructive": {
        "role": "Error and destructive action color",
        "usage": "Delete buttons, error messages, critical warnings",
        "principle": "Must signal danger or caution clearly"
      },
      "harmony_note": "All theme colors must work harmoniously together and align with brand identity. In multi-file extraction, prioritize definitions with semantic comments explaining brand intent."
    },
    "conflicts": [
      {
        "token_name": "string - which token has conflicts",
        "category": "string - colors|typography|etc",
        "definitions": [
          {
            "value": "string - token value",
            "source_file": "string - absolute path",
            "line_number": "number",
            "context": "string - surrounding comment or null",
            "semantic_intent": "string - interpretation of definition"
          }
        ],
        "selected_value": "string - final chosen value",
        "selection_reason": "string - why this value was chosen"
      }
    ],
    "code_snippets": [
      {
        "category": "colors|typography|spacing|shadows|border_radius|component",
        "token_name": "string - which token this snippet defines",
        "source_file": "string - absolute path",
        "line_start": "number",
        "line_end": "number",
        "snippet": "string - complete code block",
        "context_type": "css-variable|css-class|js-object|scss-variable|etc"
      }
    ],
    "usage_recommendations": {
      "typography": {
        "common_sizes": {
          "small_text": "sm (0.875rem)",
          "body_text": "base (1rem)",
          "heading": "2xl-4xl"
        },
        "common_combinations": [
          {
            "name": "Heading + Body",
            "heading": "2xl",
            "body": "base",
            "use_case": "Article sections"
          }
        ]
      },
      "spacing": {
        "size_guide": {
          "tight": "1-2 (0.25rem-0.5rem)",
          "normal": "4-6 (1rem-1.5rem)",
          "loose": "8-12 (2rem-3rem)"
        },
        "common_patterns": [
          {
            "pattern": "padding-4 margin-bottom-6",
            "use_case": "Card content spacing",
            "pixel_value": "1rem padding, 1.5rem margin"
          }
        ]
      }
    }
  },

  "_field_rules": {
    "schema": "$schema MUST reference W3C Design Tokens format specification",
    "colors": "All color values MUST use OKLCH format with light/dark mode values",
    "types": "All tokens MUST include $type metadata (color, dimension, duration, component, elevation)",
    "states": "Color tokens MUST include interactive states (default, hover, active, disabled) where applicable",
    "fonts": "Typography font_families MUST include Google Fonts with fallback stacks",
    "spacing": "Spacing MUST use systematic scale (multiples of 0.25rem base unit)",
    "components": "Component definitions MUST be structured objects referencing other tokens via {token.path} syntax",
    "component_states": "Component definitions MUST include state-based styling (default, hover, active, focus, disabled)",
    "elevation": "elevation z-index values MUST be defined for layered components (overlay, dropdown, dialog, tooltip)",
    "metadata_guide": "_metadata.theme_colors_guide RECOMMENDED in all modes to help users understand theme color roles and usage",
    "metadata_conflicts": "_metadata.conflicts MANDATORY in Code Import mode when conflicting definitions detected",
    "metadata_snippets": "_metadata.code_snippets ONLY present in Code Import mode",
    "metadata_recommendations": "_metadata.usage_recommendations RECOMMENDED for universal components"
  },

  "_required_components": {
    "_comment": "12+ components required, use pattern above",
    "button": "5 variants (primary, secondary, destructive, outline, ghost) + 3 sizes + states (default, hover, active, disabled, focus)",
    "card": "2 variants (default, interactive) + hover animations",
    "input": "states (default, focus, disabled, error) + 3 sizes",
    "dialog": "overlay + content + states (open, closed with animations)",
    "dropdown": "trigger (references button) + content + item (with states) + states (open, closed)",
    "toast": "2 variants (default, destructive) + states (enter, exit with animations)",
    "accordion": "trigger + content + states (open, closed with animations)",
    "tabs": "list + trigger (states: default, hover, active, disabled) + content",
    "switch": "root + thumb + states (checked, disabled)",
    "checkbox": "states (default, checked, disabled, focus)",
    "badge": "4 variants (default, secondary, destructive, outline)",
    "alert": "2 variants (default, destructive)"
  },

  "_token_reference_syntax": {
    "_comment": "Use {token.path} to reference other tokens",
    "examples": [
      "{color.interactive.primary.default}",
      "{spacing.4}",
      "{typography.font_sizes.sm}"
    ],
    "resolution": "References are resolved during CSS generation",
    "nested": "Supports nested references (e.g., {component.button.base})"
  },

  "_conflict_resolution_rules": {
    "_comment": "Code Import Mode only",
    "detect": "MUST detect when same token has different values across files",
    "read": "MUST read semantic comments (/* ... */) surrounding definitions",
    "prioritize": "MUST prioritize definitions with semantic intent over bare values",
    "record": "MUST record ALL definitions in conflicts array, not just selected one",
    "explain": "MUST explain selection_reason referencing semantic context",
    "verify": "For core theme tokens (primary, secondary, accent): MUST verify selected value aligns with overall color scheme described in comments"
  }
}
