Using Design Blocks in Child Sites

Child sites can use external design blocks through two workflows: Starwind integration (bridge-based, components work directly) and copy-paste-adapt (design reference sources, manual token adaptation). This guide covers both.

Who this is for

• Child site developers setting up Starwind components for the first time
• Developers adapting Tailwind Plus or Flowbite blocks to project tokens

Starwind integration

Starwind components are the primary installable component source for child sites. The project ships a token bridge (src/core/styles/starwind-bridge.css) that maps Starwind’s 36 CSS variables to the project’s semantic token system. Components installed via the Starwind CLI resolve project colors, dark mode, and border radius automatically.

Setup

Step 1 — Import the bridge. Add one line to src/site/styles/starwind-bridge.css:

@import "../../core/styles/starwind-bridge.css";

This should be the first @import in the file, before any component-specific styles.

Step 2 — Add your Starwind Pro license key. Create a .env.local file in the project root (if one doesn’t already exist) and add your license key:

# Starwind Pro registry setup
STARWIND_LICENSE_KEY=your_starwind_pro_license_key

Generate your key at pro.starwind.dev/account (external link) (also accessible via the Polar Portal from your account’s Quick Actions). This key is required for installing Pro components and blocks. Free components work without it.

The .env.local file is already covered by .gitignore (the .env.* pattern) — it will not be committed.

Step 3 — Install components. The project ships two preconfigured files in the project root that the Starwind CLI needs — no manual creation required:

• starwind.config.json — CLI configuration. Points componentDir to src/site/components/starwind (the site-owned zone). The CLI will add a components array to this file as you install components — that’s expected.
• components.json — Starwind component configuration (shadcn-compatible). Routes component output via aliases, points Starwind-specific CSS integration at src/site/styles/starwind-bridge.css, and configures Pro registry authentication via the registries block. Required for Pro installs; free components work without it. Do not modify the aliases or tailwind fields — they are preconfigured to match starwind.config.json.

Do not run npx starwind init — it overwrites both files. Install components individually:

# Free components
npx starwind@latest add badge
npx starwind@latest add input
npx starwind@latest add card

# Pro components (requires license key and registries config)
npx starwind@latest add @starwind-pro/hero-01

Never run npx starwind init. Only use npx starwind@latest add to install individual components.

What works immediately

Static components (~30+) — Badge, Card, Alert, Separator, Avatar, Table, and others that use only CSS classes. These resolve project brand colors and dark mode via the bridge with no additional work.

Interactive components (~10) — Accordion, Collapsible, Dialog, Dropdown Menu, Popover, Select, Sheet, Tabs, Tooltip, and others. These use vanilla JavaScript that coexists with CORE’s vanilla TypeScript. Each manages independent DOM elements — no runtime conflict. Child sites use CORE’s vanilla TS components for navigation, search, and theme switching, and Starwind’s vanilla JS for UI widgets.

Animated components — Accordion and Collapsible animations work via tw-animate-css (bundled in bridge) and the bridge’s accordion keyframe definitions.

Form components — Input, Select, Textarea, Checkbox, and Radio Group. The bridge includes @tailwindcss/forms with class strategy, which provides opt-in form utility classes (form-input, form-select, form-checkbox, form-radio). Since the class strategy does not apply global resets, Starwind form components may need explicit form-* classes for baseline input styling.

What the bridge handles

• :root aliases mapping all 36 Starwind variables to project --st-* tokens (auto-switch between light and dark modes)
• @theme inline color utility registrations so classes like bg-primary, text-muted-foreground, border-border resolve
• Accordion keyframe animations (accordion-down, accordion-up)
• tw-animate-css animation presets
• @tailwindcss/forms with class strategy (opt-in form utilities)

What the bridge does not handle

• @import "tailwindcss" — already in the project’s global.css
• @custom-variant dark — already in global.css (works for all sites, not just bridge users)
• @layer base resets — the project has its own base styles; Starwind’s resets (border-border on all elements, bg-background text-foreground on body) are excluded to avoid conflicts
• color-scheme declarations — handled by the project’s light.css and dark.css
• Radius registrations — handled by the project’s existing bridge.css

Brand color mapping

The bridge maps --secondary to the project’s brand secondary color (teal), not neutral gray as in Starwind’s defaults. Starwind components using bg-secondary will render in the project’s teal brand color.

If a child site needs neutral secondary behavior (matching Starwind’s default gray), override the mapping in src/site/styles/starwind-bridge.css after the core bridge import:

@import "../../core/styles/starwind-bridge.css";

:root {
  --secondary: var(--st-color-surface-soft);
  --secondary-foreground: var(--st-color-text-default);
}

Starwind variables such as --secondary are compatibility aliases for the Starwind component system. Normal project token values still belong in src/site/styles/primitives.css, semantic.css, light.css, and dark.css; project Tailwind utility registrations belong in src/site/styles/bridge.css; shared component CSS hook overrides belong in src/site/styles/components.css.

Icon replacement

Starwind components use Tabler icons by default. Replace them with the project’s Icon primitive:

---
import Icon from "@core/components/primitives/Icon.astro";
---

<!-- Replace Tabler icon SVGs with -->
<Icon name="check" class="size-4" />

Copy-paste-adapt workflow

Tailwind Plus and Flowbite provide HTML/CSS patterns with hardcoded Tailwind classes. These are design reference sources — no build integration exists.

Workflow

1. Copy the HTML block from the source documentation.
2. The block renders immediately — dark: variants work via the globally active @custom-variant dark.
3. Adapt hardcoded color classes to project semantic tokens:

Before:

<div class="bg-white dark:bg-gray-900 text-gray-700 dark:text-gray-300"></div>

After:

<div
  class="bg-(--st-color-bg-canvas) text-(color:--st-color-text-default)"
></div>

4. Replace dark: variant pairs with single token references where possible — the token cascade handles mode switching automatically.

Flowbite-specific notes

• Flowbite’s primary-* color classes (e.g., text-primary-700, bg-primary-50) are Flowbite’s custom color scale, not Tailwind built-ins. They do not resolve without Flowbite’s Tailwind plugin, which is not installed. Replace them with project brand tokens.
• Flowbite’s Tailwind plugin is not installed and no bridge exists — all adaptation is manual.

JS duality model

The project accepts JS duality between CORE’s vanilla TypeScript and Starwind’s vanilla JavaScript:

• CORE vanilla TypeScript owns CORE infrastructure: navigation, search modal, theme switching, mobile menu, and any custom interactive behavior authored in CORE components.
• Starwind vanilla JS owns installed UI widgets: accordion expand/collapse, dialog open/close, dropdown positioning, tooltip show/hide, and similar component-local interactions.

Both manage independent DOM elements — they do not compete for control of the same elements. This coexistence is intentional and tested.