Skip to content

Node Decision Guide

Use this guide to decide which node a new component belongs in.

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 (in nyuchi/fundi) and reads mzizi-skills plus the live mzizi-mcp server 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)

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.

  • 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
  • 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-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.

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.

  • 4.0.x = internal development patches
  • 4.1.0 = first public release
  • Major bumps (5.0.0) only for architectural redesign