Site code reference

Component rules

Where components live, how they're named and registered, and which components you must reuse or can't change.

The three folders

Folder	Holds	Examples
`src/components/sections/`	Full-width page blocks	Hero, Features, Pricing, CTA
`src/components/layout/`	Site-wide chrome reused across pages	Navbar, Footer, Container
`src/components/ui/`	Small reusable building blocks	Button, Card, Badge

Subfolders inside these are fine for organizing. A component anywhere else is refused.

Naming and identity

The editor identifies a component by its name, not its path: clicking something on the canvas finds the nearest data-component and looks that name up. Two components with the same name would make selection pick the wrong one, which is why duplicates are refused.

When a component's root isn't a single HTML element (its root is another component, a fragment, a condition or several siblings), Starjay wraps the body in one <div data-component="ComponentName" style="display:contents"> so the editor can still find it. The wrapper doesn't affect layout.

Registration is automatic

There's no registry to edit. Starjay scans the three component folders and builds the component list from the files. A new component appears in the Components tab and the Elements panel after you create it. Its description is written automatically.

Header and footer

The header and footer render on every page through the Base layout. To use a component as the header or footer, create it in src/components/layout/ and connect it with modify_layout (addComponent with slot header or footer). Don't import the header or footer into individual pages.

Layout components own their text as prop defaults, which Starjay moves into their content file. Editing a layout component changes every page.

Components used on several pages

A section component can be imported by more than one page. Before changing one that is, read each page that uses it. If the change would alter what visitors see (fields added or removed, restyled cards, required props without defaults), create a new component instead of rewriting the shared one. Adding an optional prop whose default keeps the current look is fine. After a write to a component used on several pages, the result includes a multiImporterWarning listing the affected pages.

Locked platform components

Some components come from Starjay itself and are imported from @starjay/design-system:

Component	Import
`FormBase`, `FormField`, `FormSubmit`	`@starjay/design-system/components/forms/…`
`Markdown`	`@starjay/design-system/components/cms/Markdown.astro`
`Text`	`@starjay/design-system/components/text/Text.astro`

You can't edit their source. The form components and Markdown show a Locked badge in the editor, and adding or deleting elements inside them is refused. You style them through their props. See Forms in code and Showing Markdown.