The development topic covers how to build with the theme — coding conventions, component authoring patterns, vanilla JS interactivity, icon usage, and integrating external design blocks. These guides teach the practices and patterns needed to create new components and extend existing ones.
Who this is for
- Developers — building new components, extending existing ones, or integrating external design blocks while following project conventions.
Key concepts
- Standalone section pattern — sections own their root element, background, and vertical padding. Container width and gutter control are the caller’s responsibility. See the section creation guide for the full pattern.
- Hybrid Tailwind styling — Tailwind utilities are the primary styling mechanism, with BEM class hooks for site-level overrides and scoped
<style>reserved for compound selectors and variant variable binding. - Vanilla JS islands — zero-JS by default; vanilla TypeScript provides accessible interactivity only where needed, using
data-slot/data-stateconventions andastro:page-loadlifecycle hooks. - Tiered component sourcing — external blocks from Tailwind Plus, Flowbite, Starwind, and other tier-1 sources are adapted into the project’s component system, never consumed as runtime dependencies.
In This Topic
- Development Guidelines — Coding conventions, best practices, and anti-patterns — file naming, ownership markers, hydration policy, token usage, vanilla JS patterns, performance, and common mistakes to avoid.
- Component Authoring — How to create and style components — file conventions, prop patterns, hybrid Tailwind styling, accessibility requirements, and vanilla JS integration.
- Creating a New Section Type — Step-by-step guide for adding a pure-content section component to the theme.
- Vanilla JS Interactivity Patterns — Conventions for self-contained vanilla JavaScript interactive components — data-slot, data-state, WeakMap, TypeScript classes, lifecycle hooks, and AbortController cleanup.
- Icon Usage — How to use icons — the Icon component, SVG resolution, shadowing, and accessibility.
- Design Block Integration — How the project integrates external design block sources — Tailwind Plus, Flowbite, Starwind, and custom composition.
- Animation Layer — Motion Mini animation utilities for scroll-reveal effects, presets, stagger, and reduced-motion handling.
- Using Design Blocks in Child Sites — How child sites consume Starwind components via the token bridge and adapt design reference blocks from Tailwind Plus and Flowbite.