Web & Frontendmedium risk
starlight-theme
Create and apply custom themes to an Astro Starlight documentation site. Use when customizing colors, typography, or spacing via CSS custom properties, using the Tailwind CSS integration, applying light/dark mode variants, or loading custom fonts.
pantheon-org/tekhne·skills/documentation/astro-starlight/skills/starlight-theme/SKILL.md
85/ 100品質
この Skill を導入
coding agent を選び、プロジェクト用または個人用コマンドをコピーします。
プロジェクトに導入.agents/skills/starlight-theme
npx skills add https://github.com/pantheon-org/tekhne/tree/4a79b500f771a61b6b4bf63751e038649d6535bc/skills/documentation/astro-starlight/skills/starlight-theme -a codex -y個人環境に導入~/.agents/skills/starlight-theme
npx skills add https://github.com/pantheon-org/tekhne/tree/4a79b500f771a61b6b4bf63751e038649d6535bc/skills/documentation/astro-starlight/skills/starlight-theme -a codex -g -yプロジェクトに導入.claude/skills/starlight-theme
npx skills add https://github.com/pantheon-org/tekhne/tree/4a79b500f771a61b6b4bf63751e038649d6535bc/skills/documentation/astro-starlight/skills/starlight-theme -a claude-code -y個人環境に導入~/.claude/skills/starlight-theme
npx skills add https://github.com/pantheon-org/tekhne/tree/4a79b500f771a61b6b4bf63751e038649d6535bc/skills/documentation/astro-starlight/skills/starlight-theme -a claude-code -g -yプロジェクトに導入.agents/skills/starlight-theme
npx skills add https://github.com/pantheon-org/tekhne/tree/4a79b500f771a61b6b4bf63751e038649d6535bc/skills/documentation/astro-starlight/skills/starlight-theme -a github-copilot -y個人環境に導入~/.copilot/skills/starlight-theme
npx skills add https://github.com/pantheon-org/tekhne/tree/4a79b500f771a61b6b4bf63751e038649d6535bc/skills/documentation/astro-starlight/skills/starlight-theme -a github-copilot -g -yプロジェクトに導入.agents/skills/starlight-theme
npx skills add https://github.com/pantheon-org/tekhne/tree/4a79b500f771a61b6b4bf63751e038649d6535bc/skills/documentation/astro-starlight/skills/starlight-theme -a cursor -y個人環境に導入~/.cursor/skills/starlight-theme
npx skills add https://github.com/pantheon-org/tekhne/tree/4a79b500f771a61b6b4bf63751e038649d6535bc/skills/documentation/astro-starlight/skills/starlight-theme -a cursor -g -yプロジェクトに導入.agents/skills/starlight-theme
npx skills add https://github.com/pantheon-org/tekhne/tree/4a79b500f771a61b6b4bf63751e038649d6535bc/skills/documentation/astro-starlight/skills/starlight-theme -a gemini-cli -y個人環境に導入~/.gemini/skills/starlight-theme
npx skills add https://github.com/pantheon-org/tekhne/tree/4a79b500f771a61b6b4bf63751e038649d6535bc/skills/documentation/astro-starlight/skills/starlight-theme -a gemini-cli -g -yNative Gemini CLI
gemini skills install https://github.com/pantheon-org/tekhne.git --scope workspace --path skills/documentation/astro-starlight/skills/starlight-theme⚠ インストールには open-source skills CLI を使用します。実行前にソースと権限を確認してください。
Skill の指示
GitHub で元ファイルを表示 ↗# Starlight Theming
Starlight exposes its entire visual design through CSS custom properties. Override any variable to change colors, typography, and layout — with or without Tailwind.
## When to Use
- Changing the color palette (accent color, grays, backgrounds)
- Swapping fonts or adjusting text sizes
- Applying a consistent brand identity
- Integrating Tailwind CSS into a Starlight project
## When Not to Use
- Replacing entire UI sections (header, footer, sidebar) — use `starlight-custom-component` instead
- Per-page layout changes without global theming intent
## Mindset
**Starlight styles live in CSS cascade layers. Unlayered CSS always wins.**
1. **CSS custom properties are the API.** Set `--sl-*` variables on `:root` to change every element that reads them. See [css-variables-reference.md](./references/css-variables-reference.md) for the full list.
2. **Cascade layers determine priority.** Any CSS you add without an `@layer` block is unlayered and automatically takes precedence over Starlight's named layers.
3. **Tailwind requires different wiring.** The `@astrojs/starlight-tailwind` compatibility package must be imported before Tailwind's own CSS or Starlight's styles break.
## Approach 1: Custom CSS File
**Step 1 — Create the file:**
```css
/* src/styles/custom.css */
:root {
--sl-color-accent-low: #1a1a4e;
--sl-color-accent: #3d52d5;
--sl-color-accent-high: #b4bffe;
--sl-font: 'Inter', sans-serif;
--sl-content-width: 50rem;
}
:root[data-theme='dark'] {
--sl-color-bg: #0f172a;
}
```
**Step 2 — Register in `astro.config.mjs`:**
```js
starlight({
customCss: ['./src/styles/custom.css'],
})
```
## Approach 2: Tailwind CSS Integration
```bash
npx astro add tailwind
npm install @astrojs/starlight-tailwind
```
Replace `src/styles/global.css` with:
```css
@layer base, starlight, theme, components, utilities;
@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);
@theme {
--font-sans: 'Inter';
--color-accent-500: var(--color-indigo-500);
/* Map full accent and gray scales — see references for complete example */
}
```
Update `astro.config.mjs`:
```js
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({
integrations: [starlight({ customCss: ['./src/styles/global.css'] })],
vite: { plugins: [tailwindcss()] },
});
```
See [css-variables-reference.md](./references/css-variables-reference.md) for the full Tailwind `@theme` color scale mapping.
## Anti-Patterns
### NEVER override Starlight styles without the `customCss` array
**WHY:** CSS files not registered in `customCss` are excluded from the Starlight build.
**BAD:** Add a `<style>` block in a layout component.
**GOOD:** Register a CSS file in `customCss` in `astro.config.mjs`.
**Consequence:** Styles are silently ignored.
### NEVER add raw Tailwind imports without the compatibility layer
**WHY:** Tailwind's Preflight reset conflicts with Starlight's base styles. **Consequence:** Visual regressions, broken dark mode toggle.
**BAD:** Import `tailwindcss` without `@astrojs/starlight-tailwind` first.
**GOOD:** `@import '@astrojs/starlight-tailwind'` before Tailwind imports.
### NEVER use `.dark` class selectors for dark mode
**WHY:** Starlight uses `data-theme="dark"` on `<html>`, not a `.dark` class. **Consequence:** Dark mode styles never activate.
**BAD:** `.dark:bg-gray-900` (never matches in Starlight)
**GOOD** (plain CSS):
```css
:root[data-theme='dark'] { --sl-color-bg: #0f172a; }
```
Use `dark:` Tailwind variants only after installing `@astrojs/starlight-tailwind`.
### NEVER mix `--sl-*` variables with Tailwind `@theme` overrides
**WHY:** The two systems map to each other through `@astrojs/starlight-tailwind`. Setting both creates conflicting sources of truth.
**BAD:** Set `--sl-color-accent` in CSS while also defining `--color-accent-*` in `@theme`.
**GOOD:** Choose one approach and apply all overrides through it.
**Consequence:** Colors partially apply or behave differently in light vs. dark mode.
### NEVER forget `font-display: swap` in custom `@font-face`
**WHY:** Without it, browsers may block rendering until the font downloads.
**BAD:** `@font-face { font-family: 'X'; src: url('...'); }`
**GOOD:** Add `font-display: swap;` to every `@font-face`.
**Consequence:** Flash of invisible text (FOIT) on slower connections.
## References
- [CSS Variables Reference](./references/css-variables-reference.md)
- [CSS & Styling Guide](https://starlight.astro.build/guides/css-and-tailwind/)
- [Starlight CSS variables (props.css)](https://github.com/withastro/starlight/blob/main/packages/starlight/style/props.css)
- [Color Theme Editor](https://starlight.astro.build/guides/css-and-tailwind/#theming)
- [Fontsource](https://fontsource.org/)