Cascade Layers

.changeset/shaggy-games-retire.md

@@ -0,0 +1,43 @@
+---
+'@astrojs/starlight': minor
+---
+
+Removes Shiki `css-variables` theme fallback.
+
+⚠️ **Breaking change:**
+
+Previously, Starlight used to automatically provide a fallback theme for Shiki, the default syntax highlighter built into Astro if the configured Shiki theme was not `github-dark`.
+
+This fallback was only relevant when the default Starlight code block renderer, Expressive Code, was disabled and Shiki was used. Starlight no longer provides this fallback.
+
+If you were relying on this behavior, you now manually need to update your Astro configuration to use the Shiki `css-variables` theme to match the previous behavior.
+
+```diff
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
++ markdown: {
++   shikiConfig: {
++     theme: 'css-variables',
++   },
++ },
+});
+```
+
+Additionally, you can use [custom CSS](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles) to control the appearance of the code blocks. Here is the previously used CSS variables for the fallback theme:
+
+```css
+:root {
+  --astro-code-foreground: var(--sl-color-white);
+  --astro-code-background: var(--sl-color-gray-6);
+  --astro-code-token-constant: var(--sl-color-blue-high);
+  --astro-code-token-string: var(--sl-color-green-high);
+  --astro-code-token-comment: var(--sl-color-gray-2);
+  --astro-code-token-keyword: var(--sl-color-purple-high);
+  --astro-code-token-parameter: var(--sl-color-red-high);
+  --astro-code-token-function: var(--sl-color-red-high);
+  --astro-code-token-string-expression: var(--sl-color-green-high);
+  --astro-code-token-punctuation: var(--sl-color-gray-2);
+  --astro-code-token-link: var(--sl-color-blue-high);
+}
+```

CONTRIBUTING.md

@@ -275,7 +275,7 @@ To add a language, you will need its BCP-47 tag and a label. See [“Adding a ne
 
 - Components that require client-side JavaScript or CSS should use JavaScript/CSS features that are well-supported by browsers.
 
-  You can find a list of supported browsers and their versions using this [browserslist query](https://browsersl.ist/#q=%3E+0.5%25%2C+not+dead%2C+Chrome+%3E%3D+88%2C+Edge+%3E%3D+88%2C+Firefox+%3E%3D+98%2C+Safari+%3E%3D+15.4%2C+iOS+%3E%3D+15.4%2C+not+op_mini+all). To check whether or not a feature is supported, you can visit the [Can I use](https://caniuse.com) website and search for the feature.
+  You can find a list of supported browsers and their versions using this [browserslist query](https://browsersl.ist/#q=%3E+0.5%25%2C+not+dead%2C+Chrome+%3E%3D+99%2C+Edge+%3E%3D+99%2C+Firefox+%3E%3D+98%2C+Safari+%3E%3D+15.4%2C+iOS+%3E%3D+15.4%2C+not+op_mini+all). To check whether or not a feature is supported, you can visit the [Can I use](https://caniuse.com) website and search for the feature.
 
 [discord]: https://astro.build/chat
 [issues]: https://github.com/withastro/starlight/issues

docs/astro.config.mjs

@@ -31,6 +31,8 @@ const ogUrl = new URL('og.jpg?v=1', site).href;
 const ogImageAlt = 'Make your docs shine with Starlight';
 
 export default defineConfig({
+	// TODO(HiDeoo) Remove this, only used to avoid screenshoting the dev toolbar.
+	devToolbar: { enabled: false },
 	site,
 	trailingSlash: 'always',
 	integrations: [

docs/src/components/theme-designer.astro

@@ -115,22 +115,28 @@ const {
 		}
 
 		#updateTailwindConfig({ dark, light }: ReturnType<typeof getPalettes>) {
-			const config = `import starlightPlugin from '@astrojs/starlight-tailwind';
-
-// Generated color palettes
-const accent = { 200: '${dark['accent-high']}', 600: '${light.accent}', 900: '${light['accent-high']}', 950: '${dark['accent-low']}' };
-const gray = { 100: '${light['gray-7']}', 200: '${light['gray-6']}', 300: '${light['gray-5']}', 400: '${light['gray-4']}', 500: '${light['gray-3']}', 700: '${light['gray-2']}', 800: '${light['gray-1']}', 900: '${light.white}' };
-
-/** @type {import('tailwindcss').Config} */
-export default {
-	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
-	theme: {
-		extend: {
-			colors: { accent, gray },
-		},
-	},
-	plugins: [starlightPlugin()],
-};`;
+			const config = `@layer starlight.base, starlight.reset, starlight.components, starlight.content, starlight.user-components, starlight.asides, starlight.expressive-code, starlight.utils, theme, base, components, utilities;
+
+@import '@astrojs/starlight-tailwind';
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+
+@theme {
+	/* Generated accent color palettes. */
+	--color-accent-200: ${dark['accent-high']};
+	--color-accent-600: ${light.accent};
+	--color-accent-900: ${light['accent-high']};
+	--color-accent-950: ${dark['accent-low']};
+	/* Generated gray color palettes. */
+	--color-gray-100: ${light['gray-7']};
+	--color-gray-200: ${light['gray-6']};
+	--color-gray-300: ${light['gray-5']};
+	--color-gray-400: ${light['gray-4']};
+	--color-gray-500: ${light['gray-3']};
+	--color-gray-700: ${light['gray-2']};
+	--color-gray-800: ${light['gray-1']};
+	--color-gray-900: ${light.white};
+}`;
 			const codePreview = this.querySelector('[data-theme-tailwind]');
 			if (codePreview) codePreview.innerHTML = config;
 		}

docs/src/content/docs/guides/css-and-tailwind.mdx

@@ -48,16 +48,32 @@ Customize the styles applied to your Starlight site by providing additional CSS
 
 You can see all the CSS custom properties used by Starlight that you can set to customize your site in the [`props.css` file on GitHub](https://github.com/withastro/starlight/blob/main/packages/starlight/style/props.css).
 
+Starlight uses [cascade layers](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) internally so that any custom unlayered CSS will override the default styles.
+If you are using cascade layers in your custom CSS, you can use the [`@layer`](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) CSS at-rule to define the order of precedence for different layers including the ones used by Starlight:
+
+```css /(my-(?:reset|layer))/
+@layer starlight.base,
+	my-reset,
+	starlight.reset,
+	starlight.components,
+	starlight.content,
+	starlight.user-components,
+	starlight.asides,
+	starlight.expressive-code,
+	starlight.utils,
+	my-layer;
+```
+
 ## Tailwind CSS
 
-Tailwind CSS support in Astro projects is provided by the [Astro Tailwind integration](https://docs.astro.build/en/guides/integrations-guide/tailwind/).
-Starlight provides a complementary Tailwind plugin to help configure Tailwind for compatibility with Starlight’s styles.
+Tailwind CSS support in Astro projects is provided by the [Tailwind Vite plugin](https://tailwindcss.com/docs/installation/using-vite).
+Starlight provides complementary CSS to help configure Tailwind for compatibility with Starlight’s styles.
 
-The Starlight Tailwind plugin applies the following configuration:
+The Starlight Tailwind CSS applies the following configuration:
 
 - Configures Tailwind’s `dark:` variants to work with Starlight’s dark mode.
 - Uses Tailwind [theme colors and fonts](#styling-starlight-with-tailwind) in Starlight’s UI.
-- Disables Tailwind’s [Preflight](https://tailwindcss.com/docs/preflight) reset styles while selectively restoring essential parts of Preflight required for Tailwind’s border utility classes.
+- Restore essential parts of Preflight.
 
 ### Create a new project with Tailwind
 
@@ -93,7 +109,7 @@ If you already have a Starlight site and want to add Tailwind CSS, follow these
 
 <Steps>
 
-1.  Add Astro’s Tailwind integration:
+1.  Add Tailwind Vite plugin:
 
     <Tabs syncKey="pkg">
 
@@ -123,7 +139,7 @@ If you already have a Starlight site and want to add Tailwind CSS, follow these
 
     </Tabs>
 
-2.  Install the Starlight Tailwind plugin:
+2.  Install the Starlight Tailwind CSS:
 
     <Tabs syncKey="pkg">
 
@@ -153,22 +169,51 @@ If you already have a Starlight site and want to add Tailwind CSS, follow these
 
     </Tabs>
 
-3.  Create a CSS file for Tailwind’s base styles, for example at `src/tailwind.css`:
+3.  Create a CSS file for Tailwind’s base styles, for example at `src/tailwind.css`, including Starlight Tailwind CSS:
 
-    ```css
+    ```css {4}
     /* src/tailwind.css */
-    @tailwind base;
-    @tailwind components;
-    @tailwind utilities;
+    @layer starlight.base, starlight.reset, starlight.components, starlight.content, starlight.user-components, starlight.asides, starlight.expressive-code, starlight.utils, theme, base, components, utilities;
+
+    @import '@astrojs/starlight-tailwind';
+    @import 'tailwindcss/theme.css' layer(theme);
+    @import 'tailwindcss/utilities.css' layer(utilities);
+
+    @theme {
+    	/* Your preferred accent color. Indigo is closest to Starlight’s defaults. */
+    	--color-accent-50: var(--color-indigo-50);
+    	--color-accent-100: var(--color-indigo-100);
+    	--color-accent-200: var(--color-indigo-200);
+    	--color-accent-300: var(--color-indigo-300);
+    	--color-accent-400: var(--color-indigo-400);
+    	--color-accent-500: var(--color-indigo-500);
+    	--color-accent-600: var(--color-indigo-600);
+    	--color-accent-700: var(--color-indigo-700);
+    	--color-accent-800: var(--color-indigo-800);
+    	--color-accent-900: var(--color-indigo-900);
+    	--color-accent-950: var(--color-indigo-950);
+    	/* Your preferred gray scale. Zinc is closest to Starlight’s defaults. */
+    	--color-gray-50: var(--color-zinc-50);
+    	--color-gray-100: var(--color-zinc-100);
+    	--color-gray-200: var(--color-zinc-200);
+    	--color-gray-300: var(--color-zinc-300);
+    	--color-gray-400: var(--color-zinc-400);
+    	--color-gray-500: var(--color-zinc-500);
+    	--color-gray-600: var(--color-zinc-600);
+    	--color-gray-700: var(--color-zinc-700);
+    	--color-gray-800: var(--color-zinc-800);
+    	--color-gray-900: var(--color-zinc-900);
+    	--color-gray-950: var(--color-zinc-950);
+    }
     ```
 
 4.  Update your Astro config file to use your Tailwind base styles and disable the default base styles:
 
-    ```js {11-12,16-17}
+    ```js {11-12}
     // astro.config.mjs
     import { defineConfig } from 'astro/config';
     import starlight from '@astrojs/starlight';
-    import tailwind from '@astrojs/tailwind';
+    import tailwindcss from '@tailwindcss/vite';
 
     export default defineConfig({
     	integrations: [
@@ -179,66 +224,62 @@ If you already have a Starlight site and want to add Tailwind CSS, follow these
     				'./src/tailwind.css',
     			],
     		}),
-    		tailwind({
-    			// Disable the default base styles:
-    			applyBaseStyles: false,
-    		}),
     	],
+    	vite: { plugins: [tailwindcss()] },
     });
     ```
 
-5.  Add the Starlight Tailwind plugin to `tailwind.config.mjs`:
-
-    ```js ins={2,7}
-    // tailwind.config.mjs
-    import starlightPlugin from '@astrojs/starlight-tailwind';
-
-    /** @type {import('tailwindcss').Config} */
-    export default {
-    	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
-    	plugins: [starlightPlugin()],
-    };
-    ```
-
 </Steps>
 
 ### Styling Starlight with Tailwind
 
 Starlight will use values from your [Tailwind theme config](https://tailwindcss.com/docs/theme) in its UI.
 
-If set, the following options will override Starlight’s default styles:
-
-- `colors.accent` — used for links and current item highlighting
-- `colors.gray` — used for background colors and borders
-- `fontFamily.sans` — used for UI and content text
-- `fontFamily.mono` — used for code examples
-
-```js {12,14,18,20}
-// tailwind.config.mjs
-import starlightPlugin from '@astrojs/starlight-tailwind';
-import colors from 'tailwindcss/colors';
-
-/** @type {import('tailwindcss').Config} */
-export default {
-	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
-	theme: {
-		extend: {
-			colors: {
-				// Your preferred accent color. Indigo is closest to Starlight’s defaults.
-				accent: colors.indigo,
-				// Your preferred gray scale. Zinc is closest to Starlight’s defaults.
-				gray: colors.zinc,
-			},
-			fontFamily: {
-				// Your preferred text font. Starlight uses a system font stack by default.
-				sans: ['"Atkinson Hyperlegible"'],
-				// Your preferred code font. Starlight uses system monospace fonts by default.
-				mono: ['"IBM Plex Mono"'],
-			},
-		},
-	},
-	plugins: [starlightPlugin()],
-};
+If set, the following CSS custom properties will override Starlight’s default styles:
+
+- `--color-accent-*` — used for links and current item highlighting
+- `--color-gray-*` — used for background colors and borders
+- `--sl-font` — used for UI and content text
+- `--sl-font-mono` — used for code examples
+
+```css {10-20,22-32,34,36}
+/* src/tailwind.css */
+@layer starlight.base, starlight.reset, starlight.components, starlight.content, starlight.user-components, starlight.asides, starlight.expressive-code, starlight.utils, theme, base, components, utilities;
+
+@import '@astrojs/starlight-tailwind';
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+
+@theme {
+	/* Your preferred accent color. Indigo is closest to Starlight’s defaults. */
+	--color-accent-50: var(--color-indigo-50);
+	--color-accent-100: var(--color-indigo-100);
+	--color-accent-200: var(--color-indigo-200);
+	--color-accent-300: var(--color-indigo-300);
+	--color-accent-400: var(--color-indigo-400);
+	--color-accent-500: var(--color-indigo-500);
+	--color-accent-600: var(--color-indigo-600);
+	--color-accent-700: var(--color-indigo-700);
+	--color-accent-800: var(--color-indigo-800);
+	--color-accent-900: var(--color-indigo-900);
+	--color-accent-950: var(--color-indigo-950);
+	/* Your preferred gray scale. Zinc is closest to Starlight’s defaults. */
+	--color-gray-50: var(--color-zinc-50);
+	--color-gray-100: var(--color-zinc-100);
+	--color-gray-200: var(--color-zinc-200);
+	--color-gray-300: var(--color-zinc-300);
+	--color-gray-400: var(--color-zinc-400);
+	--color-gray-500: var(--color-zinc-500);
+	--color-gray-600: var(--color-zinc-600);
+	--color-gray-700: var(--color-zinc-700);
+	--color-gray-800: var(--color-zinc-800);
+	--color-gray-900: var(--color-zinc-900);
+	--color-gray-950: var(--color-zinc-950);
+	/* Your preferred text font. Starlight uses a system font stack by default. */
+	--sl-font: 'Atkinson Hyperlegible';
+	/* Your preferred code font. Starlight uses system monospace fonts by default. */
+	--sl-font-mono: 'IBM Plex Mono';
+}
 ```
 
 ## Theming
@@ -294,8 +335,8 @@ import ThemeDesigner from '~/components/theme-designer.astro';
 		file](#custom-css-styles) to apply this theme to your site.
 	</Fragment>
 	<Fragment slot="tailwind-docs">
-		The example [Tailwind config file](#styling-starlight-with-tailwind) below
-		includes generated `accent` and `gray` color palettes to use in the
-		`theme.extend.colors` configuration object.
+		The example [Tailwind theme config](#styling-starlight-with-tailwind) below
+		includes generated `accent` and `gray` color palettes to use in the `@theme`
+		configuration directive.
 	</Fragment>
 </ThemeDesigner>

examples/tailwind/astro.config.mjs

@@ -1,7 +1,7 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
-import tailwind from '@astrojs/tailwind';
+import tailwindcss from '@tailwindcss/vite';
 
 // https://astro.build/config
 export default defineConfig({
@@ -26,6 +26,8 @@ export default defineConfig({
 			],
 			customCss: ['./src/tailwind.css'],
 		}),
-		tailwind({ applyBaseStyles: false }),
 	],
+	vite: {
+		plugins: [tailwindcss()],
+	},
 });

examples/tailwind/package.json

@@ -13,9 +13,9 @@
   "dependencies": {
     "@astrojs/starlight": "^0.32.0",
     "@astrojs/starlight-tailwind": "^3.0.0",
-    "@astrojs/tailwind": "^5.1.4",
+    "@tailwindcss/vite": "^4.0.7",
     "astro": "^5.1.5",
     "sharp": "^0.32.5",
-    "tailwindcss": "^3.4.4"
+    "tailwindcss": "^4.0.7"
   }
 }