Node Decision Guide
Use this guide to decide which node a new component belongs in.
Decision Tree
Section titled “Decision Tree”Is it a CSS value, color, spacing, or design token? → Node 1 (Tokens)
- Lives in a brand_* table (one of 18, see
get_token_counts()for the live list) - Includes minerals, semantic colors, spacing, typography, radius, shadow, motion, breakpoints, z-index, icon sizes, touch targets, density, accessibility checks, component specs
Is it a generic UI element (button, input, card, dialog, segmented-control, toolbar, bento-grid, inline-edit)? → Node 2 (Primitives)
- Must NOT import useNyuchiHarness
- Must have data-slot attribute
- Must use cn() for className composition
- Must NOT use mineral colors directly
- Hit areas follow the Bundu floor 1.1.0: 45px on touch, 24px with a fine pointer
- Pill-shaped categories (button, input, avatar, badge, toggle) use borderRadius 9999
Is it a Nyuchi-branded component with mineral palette? → Node 3 (Brand)
- Must have nyuchi- prefix on the name
- Must import useNyuchiHarness
- Must destructure { log, motion, LiveRegion }
- Must have animStyle with prefersReduced
- Must have ARIA, data-slot, focus-visible, and a 45px touch hit area (24px with a fine pointer)
Is it a verification check, content gate, or security boundary? → Node 4 (Safety)
- Platform gates: permission, content, trust, geo, rate, moderation, feature, subscription
- Chain gates: wallet, DID, chain
- Quantum gate: crypto (PQC dual-signature)
- Local-first gate: offline
Is it an error boundary, fallback, or degradation pattern? → Node 5 (Resilience)
Is it a full-screen page layout or page composition? → Node 6 (Pages)
- Must NOT render its own buttons, cards, or badges (those are L2/L3)
- Must use semantic CSS vars only (bg-card, text-foreground, bg-primary)
- Must accept children/slots for content
- Density-aware components reference brand_density tiers
Is it navigation, routing, or app lifecycle? → Node 7 (Shell)
Is it monitoring, testing, observability, or conformity validation? → Node 8 (Assurance, Z-axis)
- Examples: nyuchi-a11y-audit (accessibility validation), rtl-conformity-check (RTL layout validation), nyuchi-api-probe (health checks), nyuchi-alert-engine (SLO tracking), chaos injection
- Pattern: TypeScript module exporting typed functions plus a React hook for continuous monitoring
Is it agent logic for setting up Mzizi in a consumer project? → Node 9 (Fundi, Outside)
- Fundi is not a component you place in a layer of your app. It is the agent
that ships inside
mzizi-sdk(innyuchi/fundi) and readsmzizi-skillsplus the livemzizi-mcpserver to explore, plan, and apply setup against a consumer codebase. See the Fundi overview for the full picture.
Is it documentation, instructions, or guides? → Node 10 (Documentation)
Source Code Lives in the Database
Section titled “Source Code Lives in the Database”Every stable component carries its production TypeScript in components.source_code. The frontend repo pulls from the database at build time. To add or modify a component, write the source directly via SQL and flip its status from alpha to stable.
CSS Rules
Section titled “CSS Rules”- All CSS values live in N1 (one of the brand_* tables)
- Other nodes consume via var() references
- Zero raw Tailwind colors (bg-red-500) outside N1
- Zero inline hex except documented third-party brands (Ethereum, Google, EcoCash)
- N6 pages use only semantic CSS vars
- Use logical properties (margin-inline-start, padding-inline-end) not physical (margin-left, padding-right) for RTL support
Icon Rules
Section titled “Icon Rules”- All icons import from @/lib/icons (nyuchi-icons registry)
- Never import directly from lucide-react
- Use semantic names: Icon name=“success” not CheckCircle
- Sizing follows brand_icon_sizes (xs/sm/default/md/lg/xl from 12 to 40px)
- Mark directional icons with data-rtl-mirror=“true” if they should flip in RTL contexts
Density
Section titled “Density”Density-aware components reference brand_density tiers (compact, comfortable, spacious) by name rather than hardcoding tier behaviour. The brand_density_breakpoint_map table determines which tier loads at which viewport.
Accessibility
Section titled “Accessibility”Validate color pairs against brand_accessibility_checks before shipping new combinations. Use calculate_contrast_ratio(fg, bg) to test WCAG compliance:
- AA normal text: 4.5:1
- AA large text: 3.0:1
- AAA normal text: 7.0:1
- AAA large text: 4.5:1
High-contrast mode reads from brand_semantic_colors.hc_light_value and hc_dark_value when set.
Versioning
Section titled “Versioning”- 4.0.x = internal development patches
- 4.1.0 = first public release
- Major bumps (5.0.0) only for architectural redesign