# WorldAPI layout conventions

These are requirements for the shared WorldAPI CSS and the layout workbench. Examples are intentionally small so lightweight models can follow them without reconstructing design intent.

## Formatting

- Indent HTML, PHP, Vidoriel, JavaScript, JSON and CSS with tabs. Do not use spaces for indentation.
- Use spaces where a file format requires them; YAML does not permit tab indentation.
- Keep ordinary CSS declaration blocks on one line.
- Put every selector in a selector group on its own line; keep the declaration block on the final selector's line.
- Use multiline declaration blocks only when a rule is important or genuinely clearer that way.

```css
button,
.button { display: inline-block; padding: 1rem; }

@media (min-width: 60rem) {
	notes > main { display: grid; grid-template-columns: 24rem minmax(0, 1fr); }
}
```

## Markup

- Markup describes application meaning; CSS controls layout.
- Prefer domain-specific tags such as `<note-list>`, `<note-reader>`, `<show-title>` and `<application-header>`.
- Do not create `div` soups or generic structures such as `<list-container><list-item>`.
- Use native semantic elements such as `<main>`, `<header>`, `<footer>`, `<nav>` and `<aside>` when their HTML meaning matches the content.
- Do not add a class only to repeat an element's hierarchy. Scope it through the hierarchy when that relationship is stable.
- If an unavoidable generic layout element is needed, prefix it with `layout-`.
- Custom elements intended to be HTML-conforming must contain a hyphen. Names such as `<notes>` and `<note>` need a conforming alternative before publication.
- Classes express visual state or variants, for example `.list`, `.reader`, `.selected` and `.main` when disambiguation is necessary.
- Do not invent custom attributes or use `data-*` for layout state. Use classes, native attributes and ARIA attributes for their defined purposes.
- Do not encode misleading context in control classes. A red button is not necessarily an alert.

## Responsive behavior

- Write the smallest-screen layout first and add wider behavior with `min-width` media queries.
- Do not put breakpoint classes or responsive layout instructions into markup.
- Let Grid, Flexbox and normal flow handle layout before adding breakpoints.
- A breakpoint belongs in CSS where the content stops working, not in a device-named class.
- Different applications may have different mobile navigation models.

Examples:

- Notes: note list first on mobile; selected note replaces it. Desktop shows list and reader together.
- Landroval: message list first on mobile; mailbox list is behind a toggle; selecting a message opens the reader. Desktop shows mailboxes, messages and reader together.
- Content-first applications: main content first on mobile; secondary navigation is behind a toggle.

## CSS architecture

- The base is plain CSS, has no JavaScript dependency and is independent of Vidoriel, React, Vue, Svelte and server rendering.
- Keep foundation, reusable primitives and application layouts separate.
- Keep the existing palette, but expose semantic role tokens to component and layout CSS.
- Raw palette values belong only in the token source. Components use semantic tokens such as `--color-background`, `--color-text`, `--color-border`, `--color-action` and `--color-danger`.
- Do not hardcode palette colors in component or layout files.
- Keep selectors short and unsurprising so lightweight models can trace the cascade.

```text
css/
├── foundation/
│   ├── reset.css
│   ├── tokens.css
│   └── base.css
├── primitives/
└── layouts/
```

## Workbench

- The workbench is served from `layouts.worldapi.org`, never from the cached CDN hostname.
- Its root is project-first: `ident/`, `notes/`, `gitoria/`, `tracker/`, `landroval/`.
- Authentication variants live below the relevant project, not at the workbench root.
- Use `authenticated` and `unauthenticated` for technical fixture names. Use “signed in” and “signed out” in user-facing copy.
- Workbench CSS is local and must not import CSS from `cdn.worldapi.org`.
- The workbench must not cache HTML or CSS while layouts are being developed.
- Keep nginx autoindex enabled so fixtures and source files remain directly browsable.
- Use `layout.php` as the shared page shell and include the selected detail page into it. Do not duplicate the shell for every state.
- Included implementation fragments must not emit warnings or broken output when exposed by autoindex; either make them safe for direct access or keep them outside the public tree.

## Documentation for models

Every shared layout or component must document:

- its purpose;
- expected parent and children;
- allowed classes and states;
- narrow- and wide-screen behavior;
- native and accessibility semantics;
- one complete example;
- one short “do not use for” note when confusion is likely.

Do not rely on conversation memory. Record established decisions here and project-specific behavior beside the fixture.

## Verification

- Test the rendered result at narrow and wide viewport sizes.
- Exercise each visible state from its trigger through the expected result.
- Test long titles, empty states, overflow, focus and keyboard use.
- Verify public HTML and CSS match the current origin files; a successful `curl` alone does not prove the layout renders correctly.
- Record the exact URLs, commands and observed result in `STATUS.md`.
- A layout is not accepted as working until the user confirms it.

## Open decisions

- Final palette values, contrast targets and light-theme behavior.
- Exact breakpoint values for each layout.
- Final names for top-level application elements that currently lack the hyphen required by conforming custom-element names.
- Published CDN version paths and compatibility policy.
- Whether page-level `<header>` and `<footer>` need `.main` when hierarchy already identifies them.