Design Block Integration

The project uses a curated component sourcing strategy defined in the charter. Sources are split into two categories: Integrated Sources (child sites use directly via build-time infrastructure) and Design Reference (agents consult for CORE authoring; child sites copy-paste-adapt).

Who this is for

• CORE implementors adapting design reference blocks into the project’s component system
• Child site developers consuming Starwind components via the token bridge
• Developers building new components and deciding which source to start from

Source categories

Integrated sources

Child sites use these directly — build infrastructure handles token mapping and compatibility.

1. Starwind (external link) — bridge-enabled installable component library. Child sites import the Starwind token bridge and install components via npx starwind@latest add. Never run npx starwind init — it overwrites project configuration. The project ships preconfigured starwind.config.json and components.json files — see the Using Design Blocks in Child Sites guide for the full setup process.
2. Motion — animation engine. Core uses motion/mini; child sites may import the full package.

Design reference

Agents consult these when authoring CORE components. Child sites copy-paste-adapt patterns manually.

1. Tailwind Plus Blocks — primary HTML pattern library. Copy section HTML, convert to Astro components, adapt to project tokens.
2. Flowbite — page compositions and component patterns. Flowbite’s primary-* color scale is its own custom definition and requires manual adaptation to project tokens.
3. Tailwind UI Kit (Catalyst) — component API patterns and class composition reference.
4. Font Awesome Pro — icon library. SVGs are manually copied into the project’s icon directories (src/core/assets/icons/ and src/site/assets/icons/).
5. Custom — build from scratch only when no curated source provides an adequate pattern.

Integration process

When adapting a block from a tier-1 source into the project:

1. Select the block or pattern from the appropriate tier-1 source.
2. Create an Astro component in the correct src/core/components/ subdirectory (e.g., sections/, primitives/, ui/).
3. Replace raw HTML elements with project primitives — use Heading instead of <h1>–<h6>, Button instead of <button>, Icon instead of inline SVGs, Link instead of <a>.
4. Replace hardcoded colors with semantic tokens (--st-*). See the token adaptation section below.
5. Replace hardcoded spacing with primitive tokens or Tailwind utilities using the project’s spacing scale.
6. Add BEM class hooks for site-level override points (e.g., class="c-hero", class="c-hero__heading").
7. Add a Props interface with TypeScript types for all configurable properties.
8. Add the ownership marker — // CORE-OWNED at the top of the file.
9. Verify accessibility — keyboard operability, visible focus states, ARIA attributes where semantic HTML is insufficient.

What NOT to do

These rules differ between CORE authoring and child site consumption.

CORE authoring rules

When building or modifying CORE components (src/core/):

• Do not install design block libraries as npm dependencies for runtime use. CORE adapts patterns from design reference sources; it does not depend on them at runtime. (Build-time dependencies like tailwind-variants and tailwind-merge are permitted — they produce static output with zero client JS in SSG.)
• Do not copy CSS frameworks or utility classes. The project’s existing Tailwind v4 setup provides all utility classes. External utility CSS would conflict.
• Do not use component-specific JavaScript from external sources. CORE interactive behavior must be implemented with vanilla TypeScript, not vendor scripts.
• Do not import external fonts or assets. Use the project’s asset pipeline (src/core/assets/ and src/site/assets/).
• Do not run npx starwind init. It overwrites project configuration. See the Using Design Blocks in Child Sites guide for how to set up Starwind manually.

Child site consumption rules

When child sites consume Starwind components via the token bridge:

• Starwind dependencies are permitted. tailwind-variants and tailwind-merge are already installed as CORE production dependencies. Starwind components import them at build time.
• Starwind vanilla JS is permitted. Interactive Starwind components (~10) use vanilla JS that coexists with CORE’s vanilla TypeScript — each manages independent DOM elements. Child sites use CORE’s vanilla TS components for navigation/search/theme and Starwind’s vanilla JS for UI widgets.
• Starwind components must land in the site-owned zone. starwind.config.json must set componentDir to src/site/components/starwind. Files in src/site/ are site-owned by location — no explicit ownership markers required on auto-generated third-party files.
• Do not run npx starwind init. See the Using Design Blocks in Child Sites guide for the manual setup process including starwind.config.json creation.
• Replace Tabler icons with Font Awesome. Starwind components use Tabler icons by default; replace them with the project’s Icon primitive.

Token adaptation

External blocks use generic Tailwind classes with hardcoded color references:

<!-- External block (before adaptation) -->
<div class="bg-blue-500 text-gray-700 border-gray-200"></div>

These must be replaced with semantic token references using the v4 parenthesis shorthand:

<!-- Adapted to project tokens -->
<div
  class="bg-(--st-color-surface-soft) text-(color:--st-color-text-default) border-(--st-color-border-default)"
></div>

Note: Use the color: type hint prefix for text color tokens to disambiguate from font-size utilities, which also use the text- prefix. See the Component Authoring guide for the full token reference convention.

This adaptation ensures theme mode compatibility, brand consistency, and the ability for site-level overrides to propagate through the token cascade without modifying component internals.

Child site consumption

Child sites have two workflows for using design blocks, depending on the source category.

Starwind (integrated — bridge-based)

Starwind components work directly via the token bridge with no manual token adaptation. See the Using Design Blocks in Child Sites guide for the complete setup and workflow guide.

Design reference sources (copy-paste-adapt)

Tailwind Plus and Flowbite provide HTML/CSS patterns with hardcoded Tailwind classes. The workflow is:

1. Copy the HTML block from the source.
2. Adapt hardcoded color classes to project --st-* tokens (see token adaptation above).
3. Replace dark: variant pairs (e.g., bg-white dark:bg-gray-900) with single token references (e.g., bg-(--st-color-bg-canvas)) — the token cascade handles mode switching.
4. Flowbite blocks using primary-* colors require adaptation since that color scale is Flowbite’s custom definition, not a Tailwind built-in.

The dark: Tailwind variant is globally active via @custom-variant dark in global.css, so copied blocks with dark: utilities render correctly in both modes even before full token adaptation. This allows incremental adaptation — blocks work immediately, then can be refined to use semantic tokens.

Current limitations for design reference sources

• No token bridge exists for Flowbite or Tailwind Plus — manual token adaptation is inherent to the copy-paste format.
• Flowbite’s Tailwind plugin is not installed — Flowbite-specific utility classes (e.g., primary-*) do not resolve and must be adapted.