Community / Contributing

Contribution Guide

Everything you need to add a component, fix a bug, or propose an RFC. Read the full governance model in GOVERNANCE.md.

Setup

git clone https://github.com/danagraph/nodus-design-system
cd nodus-design-system
npm install
npm run dev       # docs site at http://localhost:3013
npm run storybook # Storybook at http://localhost:6006

Node.js 20+ required. Use npm (not pnpm) for this repo.

Directory Placement

Token Rules (Non-Negotiable)

Three-layer system. Never skip a layer. Components consume --ds-* only.

Layer 1: Primitives   tokens/bauhaus.css     --bh-red, --bh-space-4
Layer 2: Semantic     tokens/semantic.css    --ds-color-agency, --ds-space-inset-md
Layer 3: Component    (bottom of semantic)   --ds-btn-primary-bg

color: "#D42020"
background: "var(--bh-neutral-100)"
border: "1px solid var(--bh-neutral-200)"

color: "var(--ds-color-agency)"
background: "var(--ds-surface-ground)"
border: "1px solid var(--ds-border-structure)"

Minimal Component Template

"use client";

import React from "react";

interface MyComponentProps {
  children?: React.ReactNode;
  // add props here
}

export function MyComponent({ children }: MyComponentProps) {
  return (
    <div
      style={{
        background: "var(--ds-surface-raised)",
        border: "var(--ds-border-w-thin) solid var(--ds-border-structure)",
        color: "var(--ds-text-primary)",
        padding: "var(--ds-space-inset-md)",
      }}
    >
      {children}
    </div>
  );
}

Register the Component

Every component must be added to registry-extended.ts before it appears in the docs site.

// registry-extended.ts
{
  name: "my-component",
  title: "MyComponent",
  description: "One-line description of what this does.",
  category: "ui",            // ui | pattern | finance
  subcategory: "actions",    // must match subcategory keys
  status: "beta",            // stable | beta | experimental
  since: "1.4.0",
  component: MyComponent,
  source: "components/ui/MyComponent.tsx",
}

RFC Submission

Significant changes require an RFC. Copy the template and submit a PR:

cp docs/component-proposal-template.md \
   docs/rfcs/rfc-NNNN-my-component.md

# Edit the RFC, then:
git checkout -b rfc/my-component
git add docs/rfcs/rfc-NNNN-my-component.md
git commit -m "rfc: propose MyComponent (RFC-NNNN)"
gh pr create --title "RFC-NNNN: MyComponent" --label rfc

Use the Component Proposal Template for new components and GOVERNANCE.md for the full lifecycle.

PR Quality Checklist

Questions? Open a GitHub Discussion. For governance or token architecture questions, tag the Brand & Portfolio Lead.