---
name: nova-navigation-modeling
description: Model navigations with current tibi-admin-nova navigation features. Covers recursive trees, declaredTrees, singleton navigation slots, preview design, language-specific trees, and how navigation modeling fits website information architecture.
---

# nova-navigation-modeling

## When to use this skill

Use this skill when:

- Designing header, footer, service, or utility navigation for a website project
- Modeling recursive navigation trees in Nova
- Using `viewHint.navigation` with declared singleton trees
- Refactoring a flat or editor-unfriendly navigation structure

## Goal

The goal is to model navigation as a first-class website structure with current Nova support, not as an afterthought or a plain array field.

On this stack, navigation influences:

- editor workflow
- public rendering
- SSR completeness
- language structure
- information architecture

## Source of truth

Use these sources when implementing or reviewing navigation modeling:

- `tibi-admin-nova/docs/collection-config.md`
- `api/collections/navigation.yml`
- `frontend/src/App.svelte`
- the frontend navigation rendering surface

## Current Nova navigation capability

Nova supports navigation-aware collection rendering through `meta.viewHint.navigation`.

Important building blocks:

- `nodesField`
- `declaredTrees`
- singleton root identifiers
- recursive tree editing for the configured nodes field

This is more than a plain `object[]` form. Use it when the project actually has structured navigation trees.

## Recommended mental model

Model navigation by tree purpose, not by arbitrary document naming.

Typical trees:

- main/header navigation
- footer navigation
- service/navigation variants
- language-specific trees

Each tree should have a clear editorial purpose and runtime consumer.

## Declared trees and singleton slots

Use `declaredTrees` when the project has known required navigation trees.

This gives editors:

- visible expected navigation slots
- stable entry points even when a tree is not created yet
- clearer distinction between intended site structure and accidental extra entries

For website projects, this is usually better than asking editors to create free-form navigation documents manually.

## Language-specific navigation

If the website is multilingual, decide explicitly whether navigation is:

- shared across languages
- separate per language
- partially shared with localized labels

The starter's current navigation collection models separate declared trees per language and per type. That is a good default when localized slugs and labels differ.

## Node schema design

Each navigation node should represent an editorially meaningful choice.

Typical node fields:

- `name`
- internal page reference
- external toggle
- external URL
- hash/anchor
- nested child nodes

Keep the schema focused. Do not overload navigation nodes with unrelated layout or content concerns unless the runtime genuinely needs them.

## Preview design

Navigation authoring depends heavily on preview quality.

Use previews so editors can quickly tell:

- whether a node points to an internal page or external URL
- what label it displays
- which tree they are editing

The current starter navigation config already demonstrates a strong pattern: previewing internal page lookup data and external URLs differently.

## Depth and constraints

Set `maxLevel` intentionally per tree.

Examples:

- header navigation may allow two levels
- footer navigation may allow one level
- service navigation may have different limits

Depth is an information-architecture decision, not only a UI detail.

## Navigation and runtime

Navigation modeling must match the frontend and SSR expectations.

Important checks:

- the frontend knows which tree to load
- language/type keys are stable
- SSR loads navigation as page-critical shell data when needed
- internal page references remain readable in admin and resolvable in runtime

Do not design a navigation schema in admin that the frontend cannot consume cleanly.

## Recommended patterns

### Header/footer split

Recommended shape:

- separate tree purpose via singleton markers such as type/language
- separate max depth per tree
- stable declared trees for required site areas

### Internal/external mixed navigation

Recommended shape:

- explicit external toggle
- page foreign key for internal links
- external URL only when external is true
- preview that makes the choice obvious

### Multilingual navigation

Recommended shape:

- declared trees per language
- clear language field
- editor-visible grouping of the trees

## Anti-patterns

- One generic navigation document with no stable tree identity
- Weak previews that show only IDs or unclear node labels
- No explicit distinction between internal and external targets
- Unlimited nesting without an actual UX reason
- Admin tree design that does not match frontend loading/runtime rules

## Verification checklist

After changing navigation modeling, verify all of these:

1. Editors can find every intended navigation tree quickly.
2. Node previews make internal vs external links obvious.
3. Allowed depth matches the site structure.
4. Frontend loading still resolves the correct trees.
5. SSR still includes required navigation shell data.
6. `yarn validate` stays clean.

## What an LLM should inspect first

When asked to work on navigation in this starter, inspect in this order:

1. `api/collections/navigation.yml`
2. `tibi-admin-nova/docs/collection-config.md` section for `viewHint.navigation`
3. the frontend navigation loading/rendering path
4. SSR assumptions around header/footer shell data
5. the website's language and information-architecture requirements

This prevents navigation edits that are technically valid but editorially or runtime-wise incoherent.