docs: add underscore convention for system properties + update design principles

- ABSTRACTIONS.md: document _field naming convention for system frontmatter properties
  (hidden from Properties panel, editable in raw editor, stored on-disk)
- VISION.md: add design principle #9 — config stored in vault frontmatter (not localStorage)
This commit is contained in:
Test
2026-03-24 16:42:45 +01:00
parent 8207ee4569
commit e27b29eec9
2 changed files with 25 additions and 0 deletions

View File

@@ -27,6 +27,30 @@ These frontmatter field names have special meaning in Laputa's UI:
The list of default-shown relationships and semantic property rendering rules can be customized via `config/relations.md` and `config/semantic-properties.md` in the vault.
### System Properties (underscore convention)
Any frontmatter field whose name starts with `_` is a **system property**:
- It is **not shown** in the Properties panel (neither for notes nor for Type notes)
- It is **not exposed** as a user-visible property in search, filters, or the UI
- It **is editable** directly in the raw editor (power users can access it if needed)
- It is used by Laputa internally for configuration, behavior, and UI preferences
Examples:
```yaml
_pinned_properties: # which properties appear in the editor inline bar (per-type)
- key: status
icon: circle-dot
_icon: shapes # icon assigned to a type
_color: blue # color assigned to a type
_order: 10 # sort order in the sidebar
_sidebar_label: Projects # override label in sidebar
```
**This convention is universal** — apply it to all future system-level frontmatter fields. When a new feature needs to store configuration in a note's frontmatter (especially in Type notes), use `_field_name` to keep it hidden from normal user-facing surfaces while still stored on-disk as plain text.
The frontmatter parser (Rust: `vault/mod.rs`, TS: `utils/frontmatter.ts`) must filter out `_*` fields before passing `properties` to the UI.
## Document Model
All data lives in markdown files with YAML frontmatter. There is no database — the filesystem is the source of truth.

View File

@@ -192,3 +192,4 @@ Broader audiences will follow as the onboarding experience matures and the conve
6. **Capture and organize are separate** — the inbox makes unorganized notes visible; Inbox Zero is the discipline
7. **Relations as first-class citizens** — connections between notes are as important as the notes themselves
8. **Filesystem as the single source of truth** — the app never owns the data; cache and UI state are always derived and reconstructible
9. **Convention over system config files** — app configuration and preferences that belong to a note (e.g. type-level UI preferences) are stored in that note's frontmatter using the `_field` underscore convention, not in separate config files or localStorage. Everything that matters lives in the vault as plain text.