Creating components

Write the site's HTML as you normally would, split into small components. Shared CSS and JavaScript go in /assets/. Styles and scripts for a single component go inside it. See Components.

Do

Use the tag that fits the content: nav, main, article, section, footer.
Keep components small, with one job each, named after what they show.
Reuse the same component for the same element everywhere. When one is written inline, give it the exact same classes and markup as its component.
Use a CSS variable for every value you use more than once.
Name CSS variables with a consistent prefix: --color-, --font-family-, --font-size-, --font-weight-, --line-height-, --spacing-, --radius-, --shadow-, --z-index-, --container-, --transition-.
Split CSS variables into sections (colors, typography, spacing, shape, layout), each under a short header comment like /* spacing */.
End every CSS variable with a short comment on how it should be used: --spacing-md: 1rem; /* default gap between stacked elements */.
Give every third-party integration its own script in /assets/integrations/, linked only where it's needed.

Don't

Don't build everything from divs, or fake a heading with a class.
Don't hardcode one-off values like padding: 17px.
Don't put API keys, tokens or other secrets in a component. Every component is public.

FAQ

Is there a layout or include mechanism? No. Each page component writes out its own <html>, <head> and <body>. Keep it short by moving every section into its own component.

When does a piece of HTML get its own component? When it's used in more than one place or has a job of its own. A small one-off can stay inline.

Do folders matter? Not for matching, only for finding your way around the project.

Example

Page.html, Lesson.html and Product.html render whole pages. Navigation.html, Hero.html, LessonList.html and ProductList.html are sections inside them.

<!-- /components/Page.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Shadow Dojo</title>
    <link rel="stylesheet" href="/main.css">
  </head>
  <body>
    <header></header>
    <main></main>
    <footer></footer>
  </body>
</html>

A section component is just the markup of that section.

<!-- /components/Hero.html -->
<section class="hero">
  <h1>Train like a ninja</h1>
  <a class="btn" href="/lessons">See lessons</a>
</section>