{
  "skill": "starlight-theme",
  "instructions": [
    {
      "id": "customcss-registration",
      "text": "Create a CSS file and register it in the `customCss` array in `astro.config.mjs`",
      "why_given": "new knowledge",
      "original_snippets": [
        "NEVER override Starlight styles without the `customCss` array"
      ]
    },
    {
      "id": "sl-custom-properties",
      "text": "Override `--sl-*` CSS custom properties on `:root` to change colors and typography globally",
      "why_given": "new knowledge",
      "original_snippets": ["--sl-color-accent", "--sl-font"]
    },
    {
      "id": "dark-mode-selector",
      "text": "Use `:root[data-theme='dark']` and `:root[data-theme='light']` selectors for light/dark variants",
      "why_given": "new knowledge",
      "original_snippets": [":root[data-theme='dark']"]
    },
    {
      "id": "no-dark-class",
      "text": "NEVER use `.dark` class selectors — Starlight uses `data-theme='dark'` attribute, not a class",
      "why_given": "new knowledge",
      "original_snippets": ["NEVER use `.dark` class selectors"]
    },
    {
      "id": "starlight-tailwind-package",
      "text": "Install `@astrojs/starlight-tailwind` when using Tailwind with Starlight",
      "why_given": "new knowledge",
      "original_snippets": [
        "NEVER add raw Tailwind imports without the compatibility layer"
      ]
    },
    {
      "id": "tailwind-layer-order",
      "text": "Import `@astrojs/starlight-tailwind` before Tailwind's own CSS — layer order is critical",
      "why_given": "new knowledge",
      "original_snippets": ["@import '@astrojs/starlight-tailwind'"]
    },
    {
      "id": "tailwind-theme-mapping",
      "text": "Map Tailwind color tokens to Starlight via `--color-accent-*` and `--color-gray-*` in `@theme`",
      "why_given": "new knowledge",
      "original_snippets": ["--color-accent-500"]
    },
    {
      "id": "no-mixed-approaches",
      "text": "NEVER mix `--sl-*` CSS variables with Tailwind `@theme` overrides for the same property",
      "why_given": "new knowledge",
      "original_snippets": ["NEVER mix `--sl-*` variables"]
    },
    {
      "id": "font-display-swap",
      "text": "Always include `font-display: swap` in custom `@font-face` rules to prevent FOIT",
      "why_given": "new knowledge",
      "original_snippets": ["font-display: swap"]
    },
    {
      "id": "fontsource",
      "text": "Use Fontsource for zero-config font loading: install package and add weight files to `customCss`",
      "why_given": "preference",
      "original_snippets": ["@fontsource/inter"]
    },
    {
      "id": "color-theme-editor",
      "text": "Use the Starlight color theme editor to generate accent/gray palettes without manual color math",
      "why_given": "new knowledge",
      "original_snippets": ["Starlight color theme editor"]
    },
    {
      "id": "unlayered-wins",
      "text": "Any CSS added without an `@layer` block is unlayered and automatically takes precedence over Starlight",
      "why_given": "new knowledge",
      "original_snippets": ["Unlayered CSS always wins"]
    }
  ]
}