Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-038
Related:
docs/releases/v1/design/ux-principles.mddocs/releases/v1/design/readability-standards.mddocs/releases/v1/scope/immersive-vs-utilitarian-posture-rules.mddocs/releases/v1/scope/scan-first-content-hierarchy-rules.mddocs/releases/v1/specs/web-app-admin-v1-prd.mddocs/adr/ADR-0054-oshun-nisaba-first-class-customer-domain.mdapps/oshun/web/src/components/domains/NisabaSurface.tsxapps/oshun/web/src/components/library/LibraryDashboard.tsxapps/oshun/web/src/components/library/ResearchPracticeJourneyRail.tsxapps/oshun/web/src/components/search/search-config.tsapps/oshun/mobile/src/assistant/mobile-assistant-model.tsapps/oshun/mobile/src/safety/guidance.tsdocs/releases/v1/specs/todos.md
1. Purpose#
This document defines the canonical content tone for Nisaba scholarly surfaces in OSHUN V1.
Nisaba is the product's textual depth layer. Its role is to support reading, comparison, annotation, manuscripts, translations, concept lineage, and source trails across traditions.
The Nisaba tone standard exists so study surfaces feel:
- scholarly
- quiet
- precise
- contextual
- respectful of complexity
without becoming:
- theatrical
- preachy
- quote-farm inspirational
- jargon-thick
- falsely definitive
2. Current Repo Signals And Gap#
Current implementation review already shows a recognizable Nisaba voice:
NisabaSurface.tsxuses grounded study framing such asNisaba study layer,Primary texts, commentary, and comparative study,Open library,Compare translations,Open notebook, andTrace how different traditions treat disciplined action.LibraryDashboard.tsxandResearchPracticeJourneyRail.tsxalready use language likeParallel passage set,commentary notes,compare-mode anchors, andGrounded study should end in a ritual, a commitment, or a note worth returning to.search-config.tsuses scholarly search prompts such asCompare "translation notes"andFind "study notebook".mobile-assistant-model.tsframes Nisaba astext-grounded study and comparison.safety/guidance.tsalready treats Nisaba content with contextual care, explicitly warning that study material is not professional advice and that difficult passages may need pacing.OSHUN_WEB_APP_ADMIN_V1_PRD.mddefines Nisaba astextual depth, lineage, scholarship, and comparative wisdom.OSHUN_V1_IMMERSIVE_VS_UTILITARIAN_POSTURE_RULES.mdsays Nisaba immersion should feelscholarly and quiet, never theatrical.
The gap is canonical tone governance. Nisaba has strong local copy patterns, but no single rule set for how its scholarly voice should handle interpretation, tradition-specific vocabulary, comparison, caution, and cross-domain handoffs.
3. Canonical Tone Thesis#
Nisaba should sound like a thoughtful study companion and a careful research guide.
The canonical Nisaba voice is:
- serious without stiffness
- interpretive without overclaiming
- accessible without oversimplifying
- reverent toward sources without sounding devotional by default
- context-rich without becoming a wall of prose
Nisaba is allowed to feel contemplative.
Nisaba is not allowed to sound like:
- a sermon
- a self-help slogan generator
- a dissertation abstract dropped into product UI
- a mystical oracle claiming the one true reading of a text
4. Tone Pillars#
4.1 Scholarship Over Atmosphere#
Nisaba's sense of depth comes from text, lineage, and comparison, not from dramatic language.
When in doubt, make the copy more exact, not more grand.
4.2 Context Matters#
Nisaba copy should respect:
- source traditions
- translation differences
- commentary layers
- historical setting
- interpretive limits
The UI should not pretend a passage means the same thing in every setting.
4.3 Interpretive Humility#
Nisaba can compare, explain, and connect ideas.
It should not imply that one short UI sentence has exhausted the meaning of a primary text or resolved every interpretive dispute.
4.4 Quiet Precision#
Nisaba copy should feel studious and concentrated.
This means:
- low hype
- low ornament
- high signal
- calm transitions into deeper reading
4.5 Accessible Scholarship#
Nisaba should respect serious readers without excluding newer ones.
Specialized terms are acceptable, but first use should usually include enough plain-language support that the reader is not stranded.
5. Language Rules#
5.1 Sentence Shape#
- Headings should usually identify the study object or study action.
- Supporting text should explain why the item matters in one or two sentences.
- Comparative guidance should state the dimension of comparison clearly.
- Long contextual explanation belongs in expandable or dedicated reading space, not every card or chip.
5.2 Preferred Verbs#
Prefer verbs such as:
- read
- compare
- trace
- annotate
- examine
- interpret
- contextualize
- revisit
- translate
- cross-link
- preserve
These verbs fit the real work Nisaba supports.
5.3 Reference And Source Language#
- Prefer exact references, edition names, and source labels when available.
- Use terms like
passage,commentary,concept thread,edition,translation,notebook, andcompare workspacedirectly. - When summarizing a text, distinguish the passage from the commentary about the passage.
5.4 Vocabulary To Use Carefully#
Tradition-specific language is allowed when accurate, but it should not be used as decorative seasoning.
Use specialized terms only when they help the reader understand the source, concept lineage, or translation issue.
5.5 Vocabulary To Avoid#
Avoid language such as:
ancient secrettimeless hackthe universe is telling youthis quote will change your lifethe text clearly provesthe definitive meaningscholarly masterpieceas empty praise
Also avoid flattening all traditions into interchangeable inspiration snippets.
6. Surface-Specific Tone Rules#
6.1 Landing And Study-Path Surfaces#
Goal:
- orient the reader into a mode of study
Rules:
- Lead with the study object, workspace, or action.
- Use language that signals text depth and continuity.
- Do not market the surface like a lifestyle homepage.
- Make the study path explicit: open passage, compare translation, resume notebook, follow concept thread.
6.2 Passage And Reading Surfaces#
Goal:
- keep the text primary
Rules:
- Passage framing should stay quiet and exact.
- Context should support the reading rather than dominate it.
- Do not bury the reference, source, edition, or translation context.
- Avoid inspirational paraphrase that replaces the actual text.
6.3 Comparison And Translation Surfaces#
Goal:
- help the reader compare responsibly
Rules:
- Name what is being compared: edition, translation, commentary stance, morphology, lineage, or interpretation.
- Use language that invites examination, not winner-picking.
- When differences are meaningful, say that directly.
- Do not imply a single authoritative resolution unless the scholarship truly supports it.
6.4 Annotation, Highlights, And Notebooks#
Goal:
- support durable study continuity
Rules:
- Notebook and annotation copy should be precise and workmanlike.
- Labels such as
Open notebook,Resume passage, andTranslation compare workspaceare canonical because they tell the truth. - Reflection prompts may be present, but they should stay connected to the source material rather than drifting into generic journaling language.
6.5 Concept Threads And Explanatory Summaries#
Goal:
- connect ideas across texts without overclaiming
Rules:
- Concept-thread summaries should explain the comparative thread in plain language.
- Use phrasing like
trace how,compare how, orsee howrather thandiscover the true meaning. - If multiple traditions or commentaries disagree, the copy should make room for that difference instead of smoothing it away.
6.6 Assistant And Search Support Inside Nisaba#
Goal:
- accelerate study without pretending to replace it
Rules:
- Search and assistant prompts should orient toward passages, references, notebooks, and concept threads.
- Assistant explanations should cite, compare, and contextualize.
- Do not let the assistant sound like a guru or an unquestionable authority.
- If the assistant is synthesizing commentary, that synthesis should sound provisional and source-aware.
6.7 Cross-Domain Handoffs#
Goal:
- connect study to practice or verification without losing textual integrity
Rules:
- When Nisaba hands off to Tara, Arete, or Veritas, the copy should explain the connection without reducing the text to a motivational slogan.
- Cross-domain bridges should sound like continuity, not conversion.
Good:
Carry this passage into a reflection note.Compare the source trail before promoting the insight to routine.
6.8 Sensitive Passages And Context Warnings#
Goal:
- preserve seriousness and reader safety
Rules:
- Difficult passages should be described plainly, not sensationally.
- Context warnings should stay grounded, humane, and non-alarmist.
- Never romanticize grief, violence, moral injury, or historical harm in the name of gravitas.
- Remind the reader that pacing and context are legitimate parts of study.
7. Do And Do Not Examples#
| Scenario | Do | Do not |
|---|---|---|
| study hero | Primary texts, commentary, and comparative study |
Unlock ancient wisdom through immersive cosmic learning |
| passage CTA | Resume passage |
Enter the sacred quote portal |
| compare prompt | Compare four translations and note where discipline is framed differently. |
Find out which version is the most enlightened. |
| concept thread | Trace how different traditions treat disciplined action. |
Discover the universal truth hidden in all teachings. |
| notebook label | Open notebook |
Continue your soul archive |
| sensitive text warning | Some passages address grief, violence, or moral injury. |
Brace yourself for dark and powerful truths. |
| cross-domain handoff | Preserve this note, then return to Tara practice. |
Turn this verse into your next life-hack ritual. |
8. Definition Of Done For Nisaba Copy#
Nisaba copy meets the OSHUN V1 tone standard only when it is:
- scholarly without pomposity
- precise without overloading the reader
- contextual without losing scanability
- interpretive without pretending certainty
- respectful of tradition and source lineage
- quiet enough to support concentration
- careful with sensitive or difficult material
If a Nisaba surface sounds like a marketing page, a motivational quote app, or an academic paper that forgot it was a product surface, it is off-tone.