Components & Layouts

​

Structure

• layouts/ — top-level templates with named slots (header, content, footer).
• components/ — smaller pieces referenced by layouts or other components.
• schemas/ — JSON schema describing the content props a component accepts (used by editor UI).
• assets/ — images, fonts, and other static resources for the theme.

​

Component contract

• Accept a props object with content fields (title, image, text) and style tokens (color, spacing).
• Render server-side stable HTML (no client-only assumptions) so the editor preview and static rendering match.
• Expose a JSON schema for the editor UI so non-devs can edit the content safely.

​

Example component folder

themes/<theme>/components/hero/
  index.html         # server-rendered HTML fragment
  style.css          # optional auxiliary CSS
  schema.json        # editor schema for props
  README.md          # usage notes and token bindings

​

Schema example (abridged)

{
  "title": "Hero",
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "subtitle": { "type": "string" },
    "background_image": { "type": "string" },
    "variant": { "type": "string", "enum": ["default","large"] }
  }
}

​

Authoring best practices

• Keep markup semantic and accessible (use alt attributes, headings hierarchy).
• Avoid inline styles that bypass the token system; prefer CSS variables and Tailwind utilities.
• Document token bindings in each component README (which token -> which CSS var).
• Provide fallback values in components to avoid layout break on missing tokens.