✨ feat: enhance project setup and architecture documentation
- Updated `tibi-project-setup` skill to clarify project initialization goals and steps. - Improved `tibi-ssr-caching` skill to detail SSR architecture, responsibilities, and caching mechanisms. - Introduced `website-solution-architecture` skill for translating website requirements into coherent solutions. - Refined `AGENTS.md` to provide a structured roadmap for project development phases. - Added `ADMIN_ASSET_VERSION` to `api/config.yml.env` for asset versioning. - Updated SSR request flow and cache invalidation logic in `api/hooks/ssr/AGENTS.md`. - Removed obsolete `esbuild.config.admin.js` and integrated asset versioning into the main `esbuild.config.js`. - Adjusted `api/collections/content.yml` to utilize asset versioning for admin scripts.
This commit is contained in:
@@ -0,0 +1,194 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user